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