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