This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Give DynaLoader a non-dev version number.
[perl5.git] / ext / DynaLoader / DynaLoader_pm.PL
CommitLineData
03c9e98c
GS
1use Config;
2
3sub to_string {
4 my ($value) = @_;
146174a9 5 $value =~ s/\\/\\\\/g;
03c9e98c
GS
6 $value =~ s/'/\\'/g;
7 return "'$value'";
8}
9
1c7f9087
VK
10#
11# subroutine expand_os_specific expands $^O-specific preprocessing information
12# so that it will not be re-calculated at runtime in Dynaloader.pm
13#
14# Syntax of preprocessor should be kept extremely simple:
15# - directives are in double angle brackets <<...>>
16# - <<=string>> will be just evaluated
17# - for $^O-specific there are two forms:
18# <<$^O-eq-osname>>
19# <<$^O-ne-osname>>
20# this directive should be closed with respectively
21# <</$^O-eq-osname>>
22# <</$^O-ne-osname>>
23# construct <<|$^O-ne-osname>> means #else
24# nested <<$^O...>>-constructs are allowed but nested values must be for
25# different OS-names!
26#
27# -- added by VKON, 03-10-2004 to separate $^O-specific between OSes
28# (so that Win32 never checks for $^O eq 'VMS' for example)
27da23d5
JH
29#
30# The $^O tests test both for $^O and for $Config{osname}.
31# The latter is better for some for cross-compilation setups.
32#
1c7f9087
VK
33sub expand_os_specific {
34 my $s = shift;
35 for ($s) {
36 s/<<=(.*?)>>/$1/gee;
37 s/<<\$\^O-(eq|ne)-(\w+)>>(.*?)<<\/\$\^O-\1-\2>>/
38 my ($op, $os, $expr) = ($1,$2,$3);
39 if ($op ne 'eq' and $op ne 'ne') {die "wrong eq-ne arg in $&"};
40 if ($expr =~ m[^(.*?)<<\|\$\^O-$op-$os>>(.*?)$]s) {
41 # #if;#else;#endif
42 my ($if,$el) = ($1,$2);
27da23d5 43 if (($op eq 'eq' and ($^O eq $os || $Config{osname} eq $os)) || ($op eq 'ne' and ($^O ne $os || $Config{osname} ne $os))) {
1c7f9087
VK
44 $if
45 }
46 else {
47 $el
48 }
49 }
50 else {
51 # #if;#endif
27da23d5 52 if (($op eq 'eq' and ($^O eq $os || $Config{osname} eq $os)) || ($op eq 'ne' and ($^O ne $os || $Config{osname} ne $os))) {
1c7f9087
VK
53 $expr
54 }
55 else {
56 ""
57 }
58 }
59 /ges;
60 if (/<<(=|\$\^O-)/) {die "bad <<\$^O-eq/ne-osname>> expression.".
61 " Unclosed brackets?";
62 }
63 }
64 $s;
65}
66
03c9e98c
GS
67unlink "DynaLoader.pm" if -f "DynaLoader.pm";
68open OUT, ">DynaLoader.pm" or die $!;
69print OUT <<'EOT';
70
9a51af3b 71# Generated from DynaLoader_pm.PL
03c9e98c 72
a0d0e21e
LW
73package DynaLoader;
74
8e07c86e
AD
75# And Gandalf said: 'Many folk like to know beforehand what is to
76# be set on the table; but those who have laboured to prepare the
77# feast like to keep their secret; for wonder makes the words of
78# praise louder.'
79
6662521e 80# (Quote from Tolkien suggested by Anno Siegel.)
8e07c86e
AD
81#
82# See pod text at end of file for documentation.
83# See also ext/DynaLoader/README in source tree for other information.
84#
85# Tim.Bunce@ig.co.uk, August 1994
86
e240c90c 87BEGIN {
a5e412a3 88 $VERSION = '1.09';
e240c90c 89}
dc848c6f 90
dc848c6f 91require AutoLoader;
92*AUTOLOAD = \&AutoLoader::AUTOLOAD;
8e07c86e 93
7e9f3af8
JH
94use Config;
95
8e07c86e
AD
96# enable debug/trace messages from DynaLoader perl code
97$dl_debug = $ENV{PERL_DL_DEBUG} || 0 unless defined $dl_debug;
98
ff7f3c60
NIS
99#
100# Flags to alter dl_load_file behaviour. Assigned bits:
101# 0x01 make symbols available for linking later dl_load_file's.
102# (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
f86702cc 103# (ignored under VMS; effect is built-in to image linking)
ff7f3c60
NIS
104#
105# This is called as a class method $module->dl_load_flags. The
106# definition here will be inherited and result on "default" loading
107# behaviour unless a sub-class of DynaLoader defines its own version.
108#
109
110sub dl_load_flags { 0x00 }
111
03c9e98c
GS
112EOT
113
37589e1e
JD
114if ($ENV{PERL_BUILD_EXPAND_CONFIG_VARS}) {
115 print OUT "(\$dl_dlext, \$dl_so, \$dlsrc) = (",
116 to_string($Config{'dlext'}), ",",
117 to_string($Config{'so'}), ",",
118 to_string($Config{'dlsrc'}), ")\n;" ;
119}
120else {
121 print OUT <<'EOT';
122($dl_dlext, $dl_so, $dlsrc) = @Config::Config{qw(dlext so dlsrc)};
123EOT
124}
ff7f3c60 125
1c7f9087 126print OUT expand_os_specific(<<'EOT');
8e07c86e 127
1c7f9087 128<<$^O-eq-VMS>>
8e07c86e
AD
129# Some systems need special handling to expand file specifications
130# (VMS support by Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>)
131# See dl_expandspec() for more details. Should be harmless but
132# inefficient to define on systems that don't need it.
632a9a7f 133$Is_VMS = $^O eq 'VMS';
1c7f9087
VK
134<</$^O-eq-VMS>>
135$do_expand = <<$^O-eq-VMS>>1<<|$^O-eq-VMS>>0<</$^O-eq-VMS>>;
8e07c86e 136
1c7f9087 137<<$^O-eq-MacOS>>
d5201bd2 138my $Mac_FS;
1c7f9087
VK
139$Mac_FS = eval { require Mac::FileSpec::Unixish };
140<</$^O-eq-MacOS>>
d5201bd2 141
8e07c86e
AD
142@dl_require_symbols = (); # names of symbols we need
143@dl_resolve_using = (); # names of files to link with
144@dl_library_path = (); # path to look for files
bff25830
DM
145
146#XSLoader.pm may have added elements before we were required
89166d32 147#@dl_shared_objects = (); # shared objects for symbols we have
bff25830
DM
148#@dl_librefs = (); # things we have loaded
149#@dl_modules = (); # Modules we have loaded
8e07c86e
AD
150
151# This is a fix to support DLD's unfortunate desire to relink -lc
152@dl_resolve_using = dl_findfile('-lc') if $dlsrc eq "dl_dld.xs";
153
d0a5ed9f 154EOT
03c9e98c 155
d0a5ed9f 156my $cfg_dl_library_path = <<'EOT';
632a9a7f 157push(@dl_library_path, split(' ', $Config::Config{libpth}));
03c9e98c
GS
158EOT
159
d0a5ed9f 160sub dquoted_comma_list {
1c7f9087 161 join(", ", map {'"'.quotemeta($_).'"'} @_);
d0a5ed9f 162}
03c9e98c 163
d0a5ed9f
JH
164if ($ENV{PERL_BUILD_EXPAND_CONFIG_VARS}) {
165 eval $cfg_dl_library_path;
166 if (!$ENV{PERL_BUILD_EXPAND_ENV_VARS}) {
167 my $dl_library_path = dquoted_comma_list(@dl_library_path);
168 print OUT <<EOT;
7e9f3af8 169# The below \@dl_library_path has been expanded (%Config) in Perl build time.
d0a5ed9f
JH
170
171\@dl_library_path = ($dl_library_path);
172
173EOT
174 }
175}
176else {
177 print OUT <<EOT;
178# Initialise \@dl_library_path with the 'standard' library path
179# for this platform as determined by Configure.
180
181$cfg_dl_library_path
182
183EOT
184}
8e07c86e 185
8225e35f 186my $ldlibpthname;
7e9f3af8 187my $ldlibpthname_defined;
8225e35f
JH
188my $pthsep;
189
190if ($ENV{PERL_BUILD_EXPAND_CONFIG_VARS}) {
1c7f9087
VK
191 $ldlibpthname = to_string($Config::Config{ldlibpthname});
192 $ldlibpthname_defined = to_string(defined $Config::Config{ldlibpthname} ? 1 : 0);
193 $pthsep = to_string($Config::Config{path_sep});
8225e35f
JH
194}
195else {
7e9f3af8
JH
196 $ldlibpthname = q($Config::Config{ldlibpthname});
197 $ldlibpthname_defined = q(defined $Config::Config{ldlibpthname});
198 $pthsep = q($Config::Config{path_sep});
1c7f9087
VK
199}
200print OUT <<EOT;
7e9f3af8
JH
201my \$ldlibpthname = $ldlibpthname;
202my \$ldlibpthname_defined = $ldlibpthname_defined;
203my \$pthsep = $pthsep;
8225e35f
JH
204
205EOT
8225e35f 206
7e9f3af8
JH
207my $env_dl_library_path = <<'EOT';
208if ($ldlibpthname_defined &&
209 exists $ENV{$ldlibpthname}) {
210 push(@dl_library_path, split(/$pthsep/, $ENV{$ldlibpthname}));
8225e35f
JH
211}
212
5cf1d1f1 213# E.g. HP-UX supports both its native SHLIB_PATH *and* LD_LIBRARY_PATH.
8225e35f 214
7e9f3af8
JH
215if ($ldlibpthname_defined &&
216 $ldlibpthname ne 'LD_LIBRARY_PATH' &&
217 exists $ENV{LD_LIBRARY_PATH}) {
218 push(@dl_library_path, split(/$pthsep/, $ENV{LD_LIBRARY_PATH}));
d0a5ed9f 219}
e6197cab
NC
220EOT
221
d0a5ed9f
JH
222if ($ENV{PERL_BUILD_EXPAND_CONFIG_VARS} && $ENV{PERL_BUILD_EXPAND_ENV_VARS}) {
223 eval $env_dl_library_path;
e6197cab 224}
d0a5ed9f
JH
225else {
226 print OUT <<EOT;
227# Add to \@dl_library_path any extra directories we can gather from environment
228# during runtime.
e6197cab 229
d0a5ed9f
JH
230$env_dl_library_path
231
232EOT
e6197cab
NC
233}
234
d0a5ed9f
JH
235if ($ENV{PERL_BUILD_EXPAND_CONFIG_VARS} && $ENV{PERL_BUILD_EXPAND_ENV_VARS}) {
236 my $dl_library_path = dquoted_comma_list(@dl_library_path);
237 print OUT <<EOT;
7e9f3af8
JH
238# The below \@dl_library_path has been expanded (%Config, %ENV)
239# in Perl build time.
d0a5ed9f
JH
240
241\@dl_library_path = ($dl_library_path);
242
243EOT
146174a9 244}
8e07c86e 245
1c7f9087
VK
246
247# following long string contains $^O-specific stuff, which is factored out
248print OUT expand_os_specific(<<'EOT');
8e07c86e 249# No prizes for guessing why we don't say 'bootstrap DynaLoader;' here.
b4cea227 250# NOTE: All dl_*.xs (including dl_none.xs) define a dl_error() XSUB
bb3913c7 251boot_DynaLoader('DynaLoader') if defined(&boot_DynaLoader) &&
b4cea227 252 !defined(&dl_error);
8e07c86e
AD
253
254if ($dl_debug) {
255 print STDERR "DynaLoader.pm loaded (@INC, @dl_library_path)\n";
256 print STDERR "DynaLoader not linked into this perl\n"
257 unless defined(&boot_DynaLoader);
258}
259
2601; # End of main code
261
262
fb73857a 263sub croak { require Carp; Carp::croak(@_) }
264
146174a9
CB
265sub bootstrap_inherit {
266 my $module = $_[0];
267 local *isa = *{"$module\::ISA"};
268 local @isa = (@isa, 'DynaLoader');
269 # Cannot goto due to delocalization. Will report errors on a wrong line?
270 bootstrap(@_);
271}
272
8e07c86e
AD
273# The bootstrap function cannot be autoloaded (without complications)
274# so we define it here:
275
276sub bootstrap {
277 # use local vars to enable $module.bs script to edit values
278 local(@args) = @_;
279 local($module) = $args[0];
280 local(@dirs, $file);
281
fb73857a 282 unless ($module) {
283 require Carp;
284 Carp::confess("Usage: DynaLoader::bootstrap(module)");
285 }
8e07c86e
AD
286
287 # A common error on platforms which don't support dynamic loading.
288 # Since it's fatal and potentially confusing we give a detailed message.
fb73857a 289 croak("Can't load module $module, dynamic loading not available in this perl.\n".
8e07c86e
AD
290 " (You may need to build a new perl executable which either supports\n".
291 " dynamic loading or has the $module module statically linked into it.)\n")
292 unless defined(&dl_load_file);
293
59ad941d 294
1c7f9087 295 <<$^O-eq-os2>>
59ad941d
IZ
296 # Can dynaload, but cannot dynaload Perl modules...
297 die 'Dynaloaded Perl modules are not available in this build of Perl' if $OS2::is_static;
298
1c7f9087 299 <</$^O-eq-os2>>
8e07c86e
AD
300 my @modparts = split(/::/,$module);
301 my $modfname = $modparts[-1];
302
303 # Some systems have restrictions on files names for DLL's etc.
304 # mod2fname returns appropriate file base name (typically truncated)
305 # It may also edit @modparts if required.
306 $modfname = &mod2fname(\@modparts) if defined &mod2fname;
307
1c7f9087 308 <<$^O-eq-NetWare>>
1a95e36d 309 # Truncate the module name to 8.3 format for NetWare
1c7f9087 310 if ((length($modfname) > 8)) {
f355267c
JH
311 $modfname = substr($modfname, 0, 8);
312 }
1c7f9087 313 <</$^O-eq-NetWare>>
f355267c 314
1c7f9087 315 my $modpname = join(<<$^O-eq-MacOS>>':'<<|$^O-eq-MacOS>>'/'<</$^O-eq-MacOS>>,@modparts);
8e07c86e
AD
316
317 print STDERR "DynaLoader::bootstrap for $module ",
37589e1e
JD
318 <<$^O-eq-MacOS>> "(:auto:$modpname:$modfname.$dl_dlext)\n"
319 <<|$^O-eq-MacOS>>"(auto/$modpname/$modfname.$dl_dlext)\n"<</$^O-eq-MacOS>>
146174a9 320 if $dl_debug;
8e07c86e
AD
321
322 foreach (@INC) {
1c7f9087
VK
323 <<$^O-eq-VMS>>chop($_ = VMS::Filespec::unixpath($_));<</$^O-eq-VMS>>
324 <<$^O-eq-MacOS>>
e69a2255 325 my $path = $_;
5b865721 326 if ($Mac_FS && ! -d $path) {
d5201bd2
JH
327 $path = Mac::FileSpec::Unixish::nativize($path);
328 }
e69a2255 329 $path .= ":" unless /:$/;
1c7f9087
VK
330 my $dir = "${path}auto:$modpname";
331 <<|$^O-eq-MacOS>>
332 my $dir = "$_/auto/$modpname";
333 <</$^O-eq-MacOS>>
1a95e36d
JH
334
335 next unless -d $dir; # skip over uninteresting directories
336
8e07c86e 337 # check for common cases to avoid autoload of dl_findfile
37589e1e 338 my $try = <<$^O-eq-MacOS>> "$dir:$modfname.$dl_dlext" <<|$^O-eq-MacOS>> "$dir/$modfname.$dl_dlext"<</$^O-eq-MacOS>>;
1c7f9087
VK
339 last if $file = <<$^O-eq-VMS>>($do_expand) ? dl_expandspec($try) : ((-f $try) && $try);
340 <<|$^O-eq-VMS>>(-f $try) && $try;
341 <</$^O-eq-VMS>>
1a95e36d 342
8e07c86e 343 # no luck here, save dir for possible later dl_findfile search
fb73857a 344 push @dirs, $dir;
8e07c86e
AD
345 }
346 # last resort, let dl_findfile have a go in all known locations
fb73857a 347 $file = dl_findfile(map("-L$_",@dirs,@INC), $modfname) unless $file;
8e07c86e 348
fb73857a 349 croak("Can't locate loadable object for module $module in \@INC (\@INC contains: @INC)")
350 unless $file; # wording similar to error from 'require'
8e07c86e 351
1c7f9087 352 <<$^O-eq-VMS>>$file = uc($file) if $Config::Config{d_vms_case_sensitive_symbols};<</$^O-eq-VMS>>
8e07c86e
AD
353 my $bootname = "boot_$module";
354 $bootname =~ s/\W/_/g;
355 @dl_require_symbols = ($bootname);
356
357 # Execute optional '.bootstrap' perl script for this module.
358 # The .bs file can be used to configure @dl_resolve_using etc to
359 # match the needs of the individual module on this architecture.
360 my $bs = $file;
3f45a6dd 361 $bs =~ s/(\.\w+)?(;\d*)?$/\.bs/; # look for .bs 'beside' the library
8e07c86e 362 if (-s $bs) { # only read file if it's not empty
d404d5bf 363 print STDERR "BS: $bs ($^O, $dlsrc)\n" if $dl_debug;
8e07c86e
AD
364 eval { do $bs; };
365 warn "$bs: $@\n" if $@;
366 }
367
588cafc8
DM
368 my $boot_symbol_ref;
369
1c7f9087
VK
370 <<$^O-eq-darwin>>
371 if ($boot_symbol_ref = dl_find_symbol(0, $bootname)) {
372 goto boot; #extension library has already been loaded, e.g. darwin
588cafc8 373 }
1c7f9087 374 <</$^O-eq-darwin>>
588cafc8 375
8e07c86e
AD
376 # Many dynamic extension loading problems will appear to come from
377 # this section of code: XYZ failed at line 123 of DynaLoader.pm.
378 # Often these errors are actually occurring in the initialisation
379 # C code of the extension XS file. Perl reports the error as being
380 # in this perl code simply because this was the last perl code
381 # it executed.
382
ff7f3c60 383 my $libref = dl_load_file($file, $module->dl_load_flags) or
549a6b10 384 croak("Can't load '$file' for module $module: ".dl_error());
8e07c86e 385
ff7f3c60
NIS
386 push(@dl_librefs,$libref); # record loaded object
387
8e07c86e 388 my @unresolved = dl_undef_symbols();
fb73857a 389 if (@unresolved) {
390 require Carp;
391 Carp::carp("Undefined symbols present after loading $file: @unresolved\n");
392 }
8e07c86e 393
588cafc8 394 $boot_symbol_ref = dl_find_symbol($libref, $bootname) or
fb73857a 395 croak("Can't find '$bootname' symbol in $file\n");
8e07c86e 396
ff7f3c60
NIS
397 push(@dl_modules, $module); # record loaded module
398
588cafc8
DM
399 boot:
400 my $xs = dl_install_xsub("${module}::bootstrap", $boot_symbol_ref, $file);
401
8e07c86e 402 # See comment block above
8cf57410
EP
403
404 push(@dl_shared_objects, $file); # record files loaded
405
8e07c86e
AD
406 &$xs(@args);
407}
408
409
fb73857a 410#sub _check_file { # private utility to handle dl_expandspec vs -f tests
411# my($file) = @_;
412# return $file if (!$do_expand && -f $file); # the common case
413# return $file if ( $do_expand && ($file=dl_expandspec($file)));
414# return undef;
415#}
8e07c86e
AD
416
417
418# Let autosplit and the autoloader deal with these functions:
419__END__
420
421
422sub dl_findfile {
423 # Read ext/DynaLoader/DynaLoader.doc for detailed information.
424 # This function does not automatically consider the architecture
425 # or the perl library auto directories.
426 my (@args) = @_;
427 my (@dirs, $dir); # which directories to search
428 my (@found); # full paths to real files we have found
1c7f9087
VK
429 #my $dl_ext= <<=to_string($Config::Config{'dlext'})>>; # $Config::Config{'dlext'} suffix for perl extensions
430 #my $dl_so = <<=to_string($Config::Config{'so'})>>; # $Config::Config{'so'} suffix for shared libraries
8e07c86e
AD
431
432 print STDERR "dl_findfile(@args)\n" if $dl_debug;
433
434 # accumulate directories but process files as they appear
435 arg: foreach(@args) {
436 # Special fast case: full filepath requires no search
1c7f9087
VK
437 <<$^O-eq-VMS>>
438 if (m%[:>/\]]% && -f $_) {
54d6a3b3 439 push(@found,dl_expandspec(VMS::Filespec::vmsify($_)));
440 last arg unless wantarray;
441 next;
442 }
1c7f9087
VK
443 <</$^O-eq-VMS>>
444 <<$^O-eq-MacOS>>
146174a9
CB
445 if (m/:/ && -f $_) {
446 push(@found,$_);
447 last arg unless wantarray;
448 }
1c7f9087
VK
449 <</$^O-eq-MacOS>>
450 <<$^O-ne-VMS>>
451 if (m:/: && -f $_) {
8e07c86e
AD
452 push(@found,$_);
453 last arg unless wantarray;
454 next;
455 }
1c7f9087 456 <</$^O-ne-VMS>>
8e07c86e
AD
457
458 # Deal with directories first:
459 # Using a -L prefix is the preferred option (faster and more robust)
460 if (m:^-L:) { s/^-L//; push(@dirs, $_); next; }
461
1c7f9087 462 <<$^O-eq-MacOS>>
146174a9
CB
463 # Otherwise we try to try to spot directories by a heuristic
464 # (this is a more complicated issue than it first appears)
465 if (m/:/ && -d $_) { push(@dirs, $_); next; }
466 # Only files should get this far...
467 my(@names, $name); # what filenames to look for
468 s/^-l//;
469 push(@names, $_);
470 foreach $dir (@dirs, @dl_library_path) {
471 next unless -d $dir;
472 $dir =~ s/^([^:]+)$/:$1/;
473 $dir =~ s/:$//;
474 foreach $name (@names) {
475 my($file) = "$dir:$name";
476 print STDERR " checking in $dir for $name\n" if $dl_debug;
477 if (-f $file) {
478 push(@found, $file);
479 next arg; # no need to look any further
480 }
481 }
482 }
483 next;
1c7f9087 484 <</$^O-eq-MacOS>>
146174a9 485
8e07c86e
AD
486 # Otherwise we try to try to spot directories by a heuristic
487 # (this is a more complicated issue than it first appears)
488 if (m:/: && -d $_) { push(@dirs, $_); next; }
489
1c7f9087 490 <<$^O-eq-VMS>>
7e9f3af8 491 # VMS: we may be using native VMS directory syntax instead of
8e07c86e 492 # Unix emulation, so check this as well
1c7f9087
VK
493 if (/[:>\]]/ && -d $_) { push(@dirs, $_); next; }
494 <</$^O-eq-VMS>>
8e07c86e
AD
495
496 # Only files should get this far...
497 my(@names, $name); # what filenames to look for
498 if (m:-l: ) { # convert -lname to appropriate library name
499 s/-l//;
37589e1e 500 push(@names,"lib$_.$dl_so");
8e07c86e
AD
501 push(@names,"lib$_.a");
502 } else { # Umm, a bare name. Try various alternatives:
503 # these should be ordered with the most likely first
37589e1e
JD
504 push(@names,"$_.$dl_dlext") unless m/\.$dl_dlext$/o;
505 push(@names,"$_.$dl_so") unless m/\.$dl_so$/o;
506 push(@names,"lib$_.$dl_so") unless m:/:;
8e07c86e
AD
507 push(@names,"$_.a") if !m/\.a$/ and $dlsrc eq "dl_dld.xs";
508 push(@names, $_);
509 }
27da23d5
JH
510 my $dirsep = '/';
511 <<$^O-eq-symbian>>
512 $dirsep = '\\';
513 if ($0 =~ /^([a-z]):/i) {
514 my $drive = $1;
515 @dirs = map { "$drive:$_" } @dirs;
516 @dl_library_path = map { "$drive:$_" } @dl_library_path;
517 }
518 <</$^O-eq-symbian>>
8e07c86e
AD
519 foreach $dir (@dirs, @dl_library_path) {
520 next unless -d $dir;
1c7f9087
VK
521 <<$^O-eq-VMS>>
522 chop($dir = VMS::Filespec::unixpath($dir));
523 <</$^O-eq-VMS>>
8e07c86e 524 foreach $name (@names) {
27da23d5 525 my($file) = "$dir$dirsep$name";
8e07c86e 526 print STDERR " checking in $dir for $name\n" if $dl_debug;
fb73857a 527 $file = ($do_expand) ? dl_expandspec($file) : (-f $file && $file);
528 #$file = _check_file($file);
8e07c86e
AD
529 if ($file) {
530 push(@found, $file);
531 next arg; # no need to look any further
532 }
533 }
534 }
535 }
536 if ($dl_debug) {
537 foreach(@dirs) {
538 print STDERR " dl_findfile ignored non-existent directory: $_\n" unless -d $_;
539 }
540 print STDERR "dl_findfile found: @found\n";
541 }
542 return $found[0] unless wantarray;
543 @found;
544}
545
546
547sub dl_expandspec {
548 my($spec) = @_;
549 # Optional function invoked if DynaLoader.pm sets $do_expand.
550 # Most systems do not require or use this function.
551 # Some systems may implement it in the dl_*.xs file in which case
552 # this autoload version will not be called but is harmless.
553
554 # This function is designed to deal with systems which treat some
555 # 'filenames' in a special way. For example VMS 'Logical Names'
556 # (something like unix environment variables - but different).
557 # This function should recognise such names and expand them into
558 # full file paths.
559 # Must return undef if $spec is invalid or file does not exist.
560
561 my $file = $spec; # default output to input
562
1c7f9087
VK
563 <<$^O-eq-VMS>>
564 # dl_expandspec should be defined in dl_vms.xs
fb73857a 565 require Carp;
4633a7c4 566 Carp::croak("dl_expandspec: should be defined in XS file!\n");
1c7f9087 567 <<|$^O-eq-VMS>>
8e07c86e 568 return undef unless -f $file;
1c7f9087 569 <</$^O-eq-VMS>>
8e07c86e
AD
570 print STDERR "dl_expandspec($spec) => $file\n" if $dl_debug;
571 $file;
572}
573
ff7f3c60
NIS
574sub dl_find_symbol_anywhere
575{
576 my $sym = shift;
577 my $libref;
578 foreach $libref (@dl_librefs) {
579 my $symref = dl_find_symbol($libref,$sym);
580 return $symref if $symref;
581 }
582 return undef;
583}
8e07c86e 584
3b35bae3
AD
585=head1 NAME
586
587DynaLoader - Dynamically load C libraries into Perl code
588
3b35bae3
AD
589=head1 SYNOPSIS
590
8e07c86e 591 package YourPackage;
3b35bae3 592 require DynaLoader;
c2960299 593 @ISA = qw(... DynaLoader ...);
8e07c86e 594 bootstrap YourPackage;
3b35bae3 595
ff7f3c60
NIS
596 # optional method for 'global' loading
597 sub dl_load_flags { 0x01 }
598
3b35bae3
AD
599
600=head1 DESCRIPTION
601
c2960299 602This document defines a standard generic interface to the dynamic
3b35bae3
AD
603linking mechanisms available on many platforms. Its primary purpose is
604to implement automatic dynamic loading of Perl modules.
605
c2960299
AD
606This document serves as both a specification for anyone wishing to
607implement the DynaLoader for a new platform and as a guide for
608anyone wishing to use the DynaLoader directly in an application.
609
3b35bae3
AD
610The DynaLoader is designed to be a very simple high-level
611interface that is sufficiently general to cover the requirements
612of SunOS, HP-UX, NeXT, Linux, VMS and other platforms.
613
c2960299
AD
614It is also hoped that the interface will cover the needs of OS/2, NT
615etc and also allow pseudo-dynamic linking (using C<ld -A> at runtime).
3b35bae3
AD
616
617It must be stressed that the DynaLoader, by itself, is practically
618useless for accessing non-Perl libraries because it provides almost no
619Perl-to-C 'glue'. There is, for example, no mechanism for calling a C
03c9e98c 620library function or supplying arguments. A C::DynaLib module
90248788 621is available from CPAN sites which performs that function for some
1f98619c
EM
622common system types. And since the year 2000, there's also Inline::C,
623a module that allows you to write Perl subroutines in C. Also available
624from your local CPAN site.
3b35bae3
AD
625
626DynaLoader Interface Summary
627
628 @dl_library_path
629 @dl_resolve_using
630 @dl_require_symbols
631 $dl_debug
ff7f3c60
NIS
632 @dl_librefs
633 @dl_modules
8cf57410 634 @dl_shared_objects
3b35bae3
AD
635 Implemented in:
636 bootstrap($modulename) Perl
637 @filepaths = dl_findfile(@names) Perl
ff7f3c60
NIS
638 $flags = $modulename->dl_load_flags Perl
639 $symref = dl_find_symbol_anywhere($symbol) Perl
3b35bae3 640
ff7f3c60 641 $libref = dl_load_file($filename, $flags) C
abb9e9dc 642 $status = dl_unload_file($libref) C
3b35bae3
AD
643 $symref = dl_find_symbol($libref, $symbol) C
644 @symbols = dl_undef_symbols() C
645 dl_install_xsub($name, $symref [, $filename]) C
646 $message = dl_error C
647
648=over 4
649
650=item @dl_library_path
651
652The standard/default list of directories in which dl_findfile() will
653search for libraries etc. Directories are searched in order:
654$dl_library_path[0], [1], ... etc
655
656@dl_library_path is initialised to hold the list of 'normal' directories
657(F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}>). This should
658ensure portability across a wide range of platforms.
659
660@dl_library_path should also be initialised with any other directories
661that can be determined from the environment at runtime (such as
662LD_LIBRARY_PATH for SunOS).
663
664After initialisation @dl_library_path can be manipulated by an
665application using push and unshift before calling dl_findfile().
666Unshift can be used to add directories to the front of the search order
667either to save search time or to override libraries with the same name
668in the 'normal' directories.
669
670The load function that dl_load_file() calls may require an absolute
671pathname. The dl_findfile() function and @dl_library_path can be
672used to search for and return the absolute pathname for the
673library/object that you wish to load.
674
675=item @dl_resolve_using
676
677A list of additional libraries or other shared objects which can be
678used to resolve any undefined symbols that might be generated by a
679later call to load_file().
680
681This is only required on some platforms which do not handle dependent
7a2e2cd6 682libraries automatically. For example the Socket Perl extension
683library (F<auto/Socket/Socket.so>) contains references to many socket
684functions which need to be resolved when it's loaded. Most platforms
685will automatically know where to find the 'dependent' library (e.g.,
686F</usr/lib/libsocket.so>). A few platforms need to be told the
687location of the dependent library explicitly. Use @dl_resolve_using
688for this.
3b35bae3
AD
689
690Example usage:
691
692 @dl_resolve_using = dl_findfile('-lsocket');
693
694=item @dl_require_symbols
695
696A list of one or more symbol names that are in the library/object file
697to be dynamically loaded. This is only required on some platforms.
698
ff7f3c60
NIS
699=item @dl_librefs
700
701An array of the handles returned by successful calls to dl_load_file(),
702made by bootstrap, in the order in which they were loaded.
703Can be used with dl_find_symbol() to look for a symbol in any of
704the loaded files.
705
706=item @dl_modules
707
708An array of module (package) names that have been bootstrap'ed.
709
8cf57410
EP
710=item @dl_shared_objects
711
712An array of file names for the shared objects that were loaded.
713
3b35bae3
AD
714=item dl_error()
715
716Syntax:
717
718 $message = dl_error();
719
720Error message text from the last failed DynaLoader function. Note
721that, similar to errno in unix, a successful function call does not
722reset this message.
723
724Implementations should detect the error as soon as it occurs in any of
725the other functions and save the corresponding message for later
726retrieval. This will avoid problems on some platforms (such as SunOS)
727where the error message is very temporary (e.g., dlerror()).
728
729=item $dl_debug
730
731Internal debugging messages are enabled when $dl_debug is set true.
732Currently setting $dl_debug only affects the Perl side of the
733DynaLoader. These messages should help an application developer to
734resolve any DynaLoader usage problems.
735
736$dl_debug is set to C<$ENV{'PERL_DL_DEBUG'}> if defined.
737
738For the DynaLoader developer/porter there is a similar debugging
739variable added to the C code (see dlutils.c) and enabled if Perl was
740built with the B<-DDEBUGGING> flag. This can also be set via the
741PERL_DL_DEBUG environment variable. Set to 1 for minimal information or
742higher for more.
743
744=item dl_findfile()
745
746Syntax:
747
748 @filepaths = dl_findfile(@names)
749
750Determine the full paths (including file suffix) of one or more
751loadable files given their generic names and optionally one or more
752directories. Searches directories in @dl_library_path by default and
753returns an empty list if no files were found.
754
755Names can be specified in a variety of platform independent forms. Any
756names in the form B<-lname> are converted into F<libname.*>, where F<.*> is
757an appropriate suffix for the platform.
758
759If a name does not already have a suitable prefix and/or suffix then
760the corresponding file will be searched for by trying combinations of
761prefix and suffix appropriate to the platform: "$name.o", "lib$name.*"
762and "$name".
763
764If any directories are included in @names they are searched before
c2960299
AD
765@dl_library_path. Directories may be specified as B<-Ldir>. Any other
766names are treated as filenames to be searched for.
3b35bae3
AD
767
768Using arguments of the form C<-Ldir> and C<-lname> is recommended.
769
770Example:
771
772 @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));
773
774
775=item dl_expandspec()
776
777Syntax:
778
779 $filepath = dl_expandspec($spec)
780
781Some unusual systems, such as VMS, require special filename handling in
782order to deal with symbolic names for files (i.e., VMS's Logical Names).
783
784To support these systems a dl_expandspec() function can be implemented
785either in the F<dl_*.xs> file or code can be added to the autoloadable
c2960299
AD
786dl_expandspec() function in F<DynaLoader.pm>. See F<DynaLoader.pm> for
787more information.
3b35bae3
AD
788
789=item dl_load_file()
790
791Syntax:
792
ff7f3c60 793 $libref = dl_load_file($filename, $flags)
3b35bae3
AD
794
795Dynamically load $filename, which must be the path to a shared object
796or library. An opaque 'library reference' is returned as a handle for
797the loaded object. Returns undef on error.
798
ff7f3c60
NIS
799The $flags argument to alters dl_load_file behaviour.
800Assigned bits:
801
802 0x01 make symbols available for linking later dl_load_file's.
803 (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
f86702cc 804 (ignored under VMS; this is a normal part of image linking)
ff7f3c60 805
3b35bae3
AD
806(On systems that provide a handle for the loaded object such as SunOS
807and HPUX, $libref will be that handle. On other systems $libref will
808typically be $filename or a pointer to a buffer containing $filename.
809The application should not examine or alter $libref in any way.)
810
ff7f3c60
NIS
811This is the function that does the real work. It should use the
812current values of @dl_require_symbols and @dl_resolve_using if required.
3b35bae3
AD
813
814 SunOS: dlopen($filename)
815 HP-UX: shl_load($filename)
816 Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
817 NeXT: rld_load($filename, @dl_resolve_using)
818 VMS: lib$find_image_symbol($filename,$dl_require_symbols[0])
819
ff7f3c60
NIS
820(The dlopen() function is also used by Solaris and some versions of
821Linux, and is a common choice when providing a "wrapper" on other
822mechanisms as is done in the OS/2 port.)
823
abb9e9dc
GS
824=item dl_unload_file()
825
826Syntax:
827
828 $status = dl_unload_file($libref)
829
830Dynamically unload $libref, which must be an opaque 'library reference' as
831returned from dl_load_file. Returns one on success and zero on failure.
832
833This function is optional and may not necessarily be provided on all platforms.
834If it is defined, it is called automatically when the interpreter exits for
835every shared object or library loaded by DynaLoader::bootstrap. All such
836library references are stored in @dl_librefs by DynaLoader::Bootstrap as it
22851543 837loads the libraries. The files are unloaded in last-in, first-out order.
abb9e9dc
GS
838
839This unloading is usually necessary when embedding a shared-object perl (e.g.
840one configured with -Duseshrplib) within a larger application, and the perl
841interpreter is created and destroyed several times within the lifetime of the
842application. In this case it is possible that the system dynamic linker will
843unload and then subsequently reload the shared libperl without relocating any
844references to it from any files DynaLoaded by the previous incarnation of the
845interpreter. As a result, any shared objects opened by DynaLoader may point to
846a now invalid 'ghost' of the libperl shared object, causing apparently random
847memory corruption and crashes. This behaviour is most commonly seen when using
848Apache and mod_perl built with the APXS mechanism.
849
850 SunOS: dlclose($libref)
851 HP-UX: ???
852 Linux: ???
853 NeXT: ???
854 VMS: ???
855
856(The dlclose() function is also used by Solaris and some versions of
857Linux, and is a common choice when providing a "wrapper" on other
858mechanisms as is done in the OS/2 port.)
859
2307c6d0 860=item dl_load_flags()
ff7f3c60
NIS
861
862Syntax:
863
2307c6d0 864 $flags = dl_load_flags $modulename;
ff7f3c60
NIS
865
866Designed to be a method call, and to be overridden by a derived class
867(i.e. a class which has DynaLoader in its @ISA). The definition in
868DynaLoader itself returns 0, which produces standard behavior from
869dl_load_file().
3b35bae3
AD
870
871=item dl_find_symbol()
872
873Syntax:
874
875 $symref = dl_find_symbol($libref, $symbol)
876
877Return the address of the symbol $symbol or C<undef> if not found. If the
878target system has separate functions to search for symbols of different
879types then dl_find_symbol() should search for function symbols first and
880then other types.
881
882The exact manner in which the address is returned in $symref is not
883currently defined. The only initial requirement is that $symref can
884be passed to, and understood by, dl_install_xsub().
885
886 SunOS: dlsym($libref, $symbol)
887 HP-UX: shl_findsym($libref, $symbol)
888 Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
889 NeXT: rld_lookup("_$symbol")
890 VMS: lib$find_image_symbol($libref,$symbol)
891
892
ff7f3c60
NIS
893=item dl_find_symbol_anywhere()
894
895Syntax:
896
897 $symref = dl_find_symbol_anywhere($symbol)
898
899Applies dl_find_symbol() to the members of @dl_librefs and returns
900the first match found.
901
3b35bae3
AD
902=item dl_undef_symbols()
903
904Example
905
906 @symbols = dl_undef_symbols()
907
908Return a list of symbol names which remain undefined after load_file().
909Returns C<()> if not known. Don't worry if your platform does not provide
c2960299
AD
910a mechanism for this. Most do not need it and hence do not provide it,
911they just return an empty list.
3b35bae3
AD
912
913
914=item dl_install_xsub()
915
916Syntax:
917
918 dl_install_xsub($perl_name, $symref [, $filename])
919
920Create a new Perl external subroutine named $perl_name using $symref as
921a pointer to the function which implements the routine. This is simply
922a direct call to newXSUB(). Returns a reference to the installed
923function.
924
925The $filename parameter is used by Perl to identify the source file for
926the function if required by die(), caller() or the debugger. If
927$filename is not defined then "DynaLoader" will be used.
928
929
1fef88e7 930=item bootstrap()
3b35bae3
AD
931
932Syntax:
933
934bootstrap($module)
935
936This is the normal entry point for automatic dynamic loading in Perl.
937
938It performs the following actions:
939
940=over 8
941
942=item *
943
944locates an auto/$module directory by searching @INC
945
946=item *
947
948uses dl_findfile() to determine the filename to load
949
950=item *
951
952sets @dl_require_symbols to C<("boot_$module")>
953
954=item *
955
956executes an F<auto/$module/$module.bs> file if it exists
957(typically used to add to @dl_resolve_using any files which
958are required to load the module on the current platform)
959
960=item *
961
ff7f3c60
NIS
962calls dl_load_flags() to determine how to load the file.
963
964=item *
965
3b35bae3
AD
966calls dl_load_file() to load the file
967
968=item *
969
970calls dl_undef_symbols() and warns if any symbols are undefined
971
972=item *
973
974calls dl_find_symbol() for "boot_$module"
975
976=item *
977
978calls dl_install_xsub() to install it as "${module}::bootstrap"
979
980=item *
981
8e07c86e
AD
982calls &{"${module}::bootstrap"} to bootstrap the module (actually
983it uses the function reference returned by dl_install_xsub for speed)
3b35bae3
AD
984
985=back
986
987=back
988
989
990=head1 AUTHOR
991
c2960299
AD
992Tim Bunce, 11 August 1994.
993
3b35bae3
AD
994This interface is based on the work and comments of (in no particular
995order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
c2960299 996Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and others.
3b35bae3
AD
997
998Larry Wall designed the elegant inherited bootstrap mechanism and
999implemented the first Perl 5 dynamic loader using it.
1000
ff7f3c60
NIS
1001Solaris global loading added by Nick Ing-Simmons with design/coding
1002assistance from Tim Bunce, January 1996.
1003
3b35bae3 1004=cut
03c9e98c
GS
1005EOT
1006
1007close OUT or die $!;
1008