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