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