ext/DynaLoader/DynaLoader_pm.PL

   1
   2 use Config;
   3
   4 sub to_string {
   5     my ($value) = @_;
   6     $value =~ s/\\/\\\\/g;
   7     $value =~ s/'/\\'/g;
   8     return "'$value'";
   9 }
  10
  11 unlink "DynaLoader.pm" if -f "DynaLoader.pm";
  12 open OUT, ">DynaLoader.pm" or die $!;
  13 print OUT <<'EOT';
  14
  15 # Generated from DynaLoader.pm.PL (resolved %Config::Config values)
  16
  17 package DynaLoader;
  18
  19 #   And Gandalf said: 'Many folk like to know beforehand what is to
  20 #   be set on the table; but those who have laboured to prepare the
  21 #   feast like to keep their secret; for wonder makes the words of
  22 #   praise louder.'
  23
  24 #   (Quote from Tolkien sugested by Anno Siegel.)
  25 #
  26 # See pod text at end of file for documentation.
  27 # See also ext/DynaLoader/README in source tree for other information.
  28 #
  29 # Tim.Bunce@ig.co.uk, August 1994
  30
  31 $VERSION = "1.03";      # avoid typo warning
  32
  33 require AutoLoader;
  34 *AUTOLOAD = \&AutoLoader::AUTOLOAD;
  35
  36 # The following require can't be removed during maintenance
  37 # releases, sadly, because of the risk of buggy code that does
  38 # require Carp; Carp::croak "..."; without brackets dying
  39 # if Carp hasn't been loaded in earlier compile time. :-(
  40 # We'll let those bugs get found on the development track.
  41 require Carp if $] < 5.00450;
  42
  43
  44 # enable debug/trace messages from DynaLoader perl code
  45 $dl_debug = $ENV{PERL_DL_DEBUG} || 0 unless defined $dl_debug;
  46
  47 #
  48 # Flags to alter dl_load_file behaviour.  Assigned bits:
  49 #   0x01  make symbols available for linking later dl_load_file's.
  50 #         (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
  51 #         (ignored under VMS; effect is built-in to image linking)
  52 #
  53 # This is called as a class method $module->dl_load_flags.  The
  54 # definition here will be inherited and result on "default" loading
  55 # behaviour unless a sub-class of DynaLoader defines its own version.
  56 #
  57
  58 sub dl_load_flags { 0x00 }
  59
  60 # ($dl_dlext, $dlsrc)
  61 #         = @Config::Config{'dlext', 'dlsrc'};
  62 EOT
  63
  64 print OUT "  (\$dl_dlext, \$dlsrc) = (",
  65           to_string($Config::Config{'dlext'}), ",",
  66           to_string($Config::Config{'dlsrc'}), ")\n;" ;
  67
  68 print OUT <<'EOT';
  69
  70 # Some systems need special handling to expand file specifications
  71 # (VMS support by Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>)
  72 # See dl_expandspec() for more details. Should be harmless but
  73 # inefficient to define on systems that don't need it.
  74 $do_expand = $Is_VMS = $^O eq 'VMS';
  75 $Is_MacOS  = $^O eq 'MacOS';
  76
  77 @dl_require_symbols = ();       # names of symbols we need
  78 @dl_resolve_using   = ();       # names of files to link with
  79 @dl_library_path    = ();       # path to look for files
  80 @dl_librefs         = ();       # things we have loaded
  81 @dl_modules         = ();       # Modules we have loaded
  82
  83 # This is a fix to support DLD's unfortunate desire to relink -lc
  84 @dl_resolve_using = dl_findfile('-lc') if $dlsrc eq "dl_dld.xs";
  85
  86 # Initialise @dl_library_path with the 'standard' library path
  87 # for this platform as determined by Configure
  88
  89 # push(@dl_library_path, split(' ', $Config::Config{'libpth'});
  90 EOT
  91
  92 print OUT "push(\@dl_library_path, split(' ', ",
  93           to_string($Config::Config{'libpth'}), "));\n";
  94
  95 print OUT <<'EOT';
  96
  97 # Add to @dl_library_path any extra directories we can gather
  98 # from environment variables.
  99 if ($Is_MacOS) {
 100     push(@dl_library_path, split(/,/, $ENV{LD_LIBRARY_PATH}))
 101         if exists $ENV{LD_LIBRARY_PATH};
 102 } else {
 103     push(@dl_library_path, split(/:/, $ENV{$Config::Config{ldlibpthname}}))
 104         if exists      $Config::Config{ldlibpthname}        &&
 105                        $Config::Config{ldlibpthname}  ne '' &&
 106                 exists $ENV{$Config::Config{ldlibpthname}}       ;;
 107     push(@dl_library_path, split(/:/, $ENV{$Config::Config{ldlibpthname}}))
 108         if exists      $Config::Config{ldlibpthname}        &&
 109                        $Config::Config{ldlibpthname}  ne '' &&
 110                 exists $ENV{$Config::Config{ldlibpthname}}       ;;
 111 # E.g. HP-UX supports both its native SHLIB_PATH *and* LD_LIBRARY_PATH.
 112 push(@dl_library_path, split(/:/, $ENV{LD_LIBRARY_PATH}))
 113     if exists $ENV{LD_LIBRARY_PATH};
 114 }
 115
 116 # No prizes for guessing why we don't say 'bootstrap DynaLoader;' here.
 117 boot_DynaLoader('DynaLoader') if defined(&boot_DynaLoader) &&
 118                                 !defined(&dl_load_file);
 119
 120
 121 if ($dl_debug) {
 122     print STDERR "DynaLoader.pm loaded (@INC, @dl_library_path)\n";
 123     print STDERR "DynaLoader not linked into this perl\n"
 124             unless defined(&boot_DynaLoader);
 125 }
 126
 127 1; # End of main code
 128
 129
 130 sub croak   { require Carp; Carp::croak(@_)   }
 131
 132 sub bootstrap_inherit {
 133     my $module = $_[0];
 134     local *isa = *{"$module\::ISA"};
 135     local @isa = (@isa, 'DynaLoader');
 136     # Cannot goto due to delocalization.  Will report errors on a wrong line?
 137     bootstrap(@_);
 138 }
 139
 140 # The bootstrap function cannot be autoloaded (without complications)
 141 # so we define it here:
 142
 143 sub bootstrap {
 144     # use local vars to enable $module.bs script to edit values
 145     local(@args) = @_;
 146     local($module) = $args[0];
 147     local(@dirs, $file);
 148
 149     unless ($module) {
 150         require Carp;
 151         Carp::confess("Usage: DynaLoader::bootstrap(module)");
 152     }
 153
 154     # A common error on platforms which don't support dynamic loading.
 155     # Since it's fatal and potentially confusing we give a detailed message.
 156     croak("Can't load module $module, dynamic loading not available in this perl.\n".
 157         "  (You may need to build a new perl executable which either supports\n".
 158         "  dynamic loading or has the $module module statically linked into it.)\n")
 159         unless defined(&dl_load_file);
 160
 161     my @modparts = split(/::/,$module);
 162     my $modfname = $modparts[-1];
 163
 164     # Some systems have restrictions on files names for DLL's etc.
 165     # mod2fname returns appropriate file base name (typically truncated)
 166     # It may also edit @modparts if required.
 167     $modfname = &mod2fname(\@modparts) if defined &mod2fname;
 168
 169     my $modpname = join(($Is_MacOS ? ':' : '/'),@modparts);
 170
 171     print STDERR "DynaLoader::bootstrap for $module ",
 172                 ($Is_MacOS
 173                       ? "(auto/$modpname/$modfname.$dl_dlext)\n" :
 174                         "(:auto:$modpname:$modfname.$dl_dlext)\n")
 175         if $dl_debug;
 176
 177     foreach (@INC) {
 178         chop($_ = VMS::Filespec::unixpath($_)) if $Is_VMS;
 179         my $dir;
 180         if ($Is_MacOS) {
 181             chop $_  if /:$/;
 182             $dir = "$_:auto:$modpname";
 183         } else {
 184             $dir = "$_/auto/$modpname";
 185         }
 186         next unless -d $dir; # skip over uninteresting directories
 187
 188         # check for common cases to avoid autoload of dl_findfile
 189         my $try = $Is_MacOS ? "$dir:$modfname.$dl_dlext" : "$dir/$modfname.$dl_dlext";
 190         last if $file = ($do_expand) ? dl_expandspec($try) : (-f $try && $try);
 191
 192         # no luck here, save dir for possible later dl_findfile search
 193         push @dirs, $dir;
 194     }
 195     # last resort, let dl_findfile have a go in all known locations
 196     $file = dl_findfile(map("-L$_",@dirs,@INC), $modfname) unless $file;
 197
 198     croak("Can't locate loadable object for module $module in \@INC (\@INC contains: @INC)")
 199         unless $file;   # wording similar to error from 'require'
 200
 201     my $bootname = "boot_$module";
 202     $bootname =~ s/\W/_/g;
 203     @dl_require_symbols = ($bootname);
 204
 205     # Execute optional '.bootstrap' perl script for this module.
 206     # The .bs file can be used to configure @dl_resolve_using etc to
 207     # match the needs of the individual module on this architecture.
 208     my $bs = $file;
 209     $bs =~ s/(\.\w+)?(;\d*)?$/\.bs/; # look for .bs 'beside' the library
 210     if (-s $bs) { # only read file if it's not empty
 211         print STDERR "BS: $bs ($^O, $dlsrc)\n" if $dl_debug;
 212         eval { do $bs; };
 213         warn "$bs: $@\n" if $@;
 214     }
 215
 216     # Many dynamic extension loading problems will appear to come from
 217     # this section of code: XYZ failed at line 123 of DynaLoader.pm.
 218     # Often these errors are actually occurring in the initialisation
 219     # C code of the extension XS file. Perl reports the error as being
 220     # in this perl code simply because this was the last perl code
 221     # it executed.
 222
 223     my $libref = dl_load_file($file, $module->dl_load_flags) or
 224         croak("Can't load '$file' for module $module: ".dl_error());
 225
 226     push(@dl_librefs,$libref);  # record loaded object
 227
 228     my @unresolved = dl_undef_symbols();
 229     if (@unresolved) {
 230         require Carp;
 231         Carp::carp("Undefined symbols present after loading $file: @unresolved\n");
 232     }
 233
 234     my $boot_symbol_ref = dl_find_symbol($libref, $bootname) or
 235          croak("Can't find '$bootname' symbol in $file\n");
 236
 237     my $xs = dl_install_xsub("${module}::bootstrap", $boot_symbol_ref, $file);
 238
 239     push(@dl_modules, $module); # record loaded module
 240
 241     # See comment block above
 242     &$xs(@args);
 243 }
 244
 245
 246 #sub _check_file {   # private utility to handle dl_expandspec vs -f tests
 247 #    my($file) = @_;
 248 #    return $file if (!$do_expand && -f $file); # the common case
 249 #    return $file if ( $do_expand && ($file=dl_expandspec($file)));
 250 #    return undef;
 251 #}
 252
 253
 254 # Let autosplit and the autoloader deal with these functions:
 255 __END__
 256
 257
 258 sub dl_findfile {
 259     # Read ext/DynaLoader/DynaLoader.doc for detailed information.
 260     # This function does not automatically consider the architecture
 261     # or the perl library auto directories.
 262     my (@args) = @_;
 263     my (@dirs,  $dir);   # which directories to search
 264     my (@found);         # full paths to real files we have found
 265 EOT
 266
 267 print OUT '    my $dl_ext= ' . to_string($Config::Config{'dlext'}) .
 268           "; # \$Config::Config{'dlext'} suffix for perl extensions\n";
 269 print OUT '    my $dl_so = ' . to_string($Config::Config{'so'}) .
 270           "; # \$Config::Config{'so'} suffix for shared libraries\n";
 271
 272 print OUT <<'EOT';
 273
 274     print STDERR "dl_findfile(@args)\n" if $dl_debug;
 275
 276     # accumulate directories but process files as they appear
 277     arg: foreach(@args) {
 278         #  Special fast case: full filepath requires no search
 279         if ($Is_VMS && m%[:>/\]]% && -f $_) {
 280             push(@found,dl_expandspec(VMS::Filespec::vmsify($_)));
 281             last arg unless wantarray;
 282             next;
 283         }
 284         elsif ($Is_MacOS) {
 285             if (m/:/ && -f $_) {
 286                 push(@found,$_);
 287                 last arg unless wantarray;
 288             }
 289         }
 290         elsif (m:/: && -f $_ && !$do_expand) {
 291             push(@found,$_);
 292             last arg unless wantarray;
 293             next;
 294         }
 295
 296         # Deal with directories first:
 297         #  Using a -L prefix is the preferred option (faster and more robust)
 298         if (m:^-L:) { s/^-L//; push(@dirs, $_); next; }
 299
 300         if ($Is_MacOS) {
 301             #  Otherwise we try to try to spot directories by a heuristic
 302             #  (this is a more complicated issue than it first appears)
 303             if (m/:/ && -d $_) {   push(@dirs, $_); next; }
 304             #  Only files should get this far...
 305             my(@names, $name);    # what filenames to look for
 306             s/^-l//;
 307             push(@names, $_);
 308             foreach $dir (@dirs, @dl_library_path) {
 309                 next unless -d $dir;
 310                 $dir =~ s/^([^:]+)$/:$1/;
 311                 $dir =~ s/:$//;
 312                 foreach $name (@names) {
 313                     my($file) = "$dir:$name";
 314                     print STDERR " checking in $dir for $name\n" if $dl_debug;
 315                     if (-f $file) {
 316                         push(@found, $file);
 317                         next arg; # no need to look any further
 318                     }
 319                 }
 320             }
 321             next;
 322         }
 323
 324         #  Otherwise we try to try to spot directories by a heuristic
 325         #  (this is a more complicated issue than it first appears)
 326         if (m:/: && -d $_) {   push(@dirs, $_); next; }
 327
 328         # VMS: we may be using native VMS directry syntax instead of
 329         # Unix emulation, so check this as well
 330         if ($Is_VMS && /[:>\]]/ && -d $_) {   push(@dirs, $_); next; }
 331
 332         #  Only files should get this far...
 333         my(@names, $name);    # what filenames to look for
 334         if (m:-l: ) {          # convert -lname to appropriate library name
 335             s/-l//;
 336             push(@names,"lib$_.$dl_so");
 337             push(@names,"lib$_.a");
 338         } else {                # Umm, a bare name. Try various alternatives:
 339             # these should be ordered with the most likely first
 340             push(@names,"$_.$dl_ext")    unless m/\.$dl_ext$/o;
 341             push(@names,"$_.$dl_so")     unless m/\.$dl_so$/o;
 342             push(@names,"lib$_.$dl_so")  unless m:/:;
 343             push(@names,"$_.a")          if !m/\.a$/ and $dlsrc eq "dl_dld.xs";
 344             push(@names, $_);
 345         }
 346         foreach $dir (@dirs, @dl_library_path) {
 347             next unless -d $dir;
 348             chop($dir = VMS::Filespec::unixpath($dir)) if $Is_VMS;
 349             foreach $name (@names) {
 350                 my($file) = "$dir/$name";
 351                 print STDERR " checking in $dir for $name\n" if $dl_debug;
 352                 $file = ($do_expand) ? dl_expandspec($file) : (-f $file && $file);
 353                 #$file = _check_file($file);
 354                 if ($file) {
 355                     push(@found, $file);
 356                     next arg; # no need to look any further
 357                 }
 358             }
 359         }
 360     }
 361     if ($dl_debug) {
 362         foreach(@dirs) {
 363             print STDERR " dl_findfile ignored non-existent directory: $_\n" unless -d $_;
 364         }
 365         print STDERR "dl_findfile found: @found\n";
 366     }
 367     return $found[0] unless wantarray;
 368     @found;
 369 }
 370
 371
 372 sub dl_expandspec {
 373     my($spec) = @_;
 374     # Optional function invoked if DynaLoader.pm sets $do_expand.
 375     # Most systems do not require or use this function.
 376     # Some systems may implement it in the dl_*.xs file in which case
 377     # this autoload version will not be called but is harmless.
 378
 379     # This function is designed to deal with systems which treat some
 380     # 'filenames' in a special way. For example VMS 'Logical Names'
 381     # (something like unix environment variables - but different).
 382     # This function should recognise such names and expand them into
 383     # full file paths.
 384     # Must return undef if $spec is invalid or file does not exist.
 385
 386     my $file = $spec; # default output to input
 387
 388     if ($Is_VMS) { # dl_expandspec should be defined in dl_vms.xs
 389         require Carp;
 390         Carp::croak("dl_expandspec: should be defined in XS file!\n");
 391     } else {
 392         return undef unless -f $file;
 393     }
 394     print STDERR "dl_expandspec($spec) => $file\n" if $dl_debug;
 395     $file;
 396 }
 397
 398 sub dl_find_symbol_anywhere
 399 {
 400     my $sym = shift;
 401     my $libref;
 402     foreach $libref (@dl_librefs) {
 403         my $symref = dl_find_symbol($libref,$sym);
 404         return $symref if $symref;
 405     }
 406     return undef;
 407 }
 408
 409 =head1 NAME
 410
 411 DynaLoader - Dynamically load C libraries into Perl code
 412
 413 dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_find_symbol(), dl_find_symbol_anywhere(), dl_undef_symbols(), dl_install_xsub(), dl_load_flags(), bootstrap() - routines used by DynaLoader modules
 414
 415 =head1 SYNOPSIS
 416
 417     package YourPackage;
 418     require DynaLoader;
 419     @ISA = qw(... DynaLoader ...);
 420     bootstrap YourPackage;
 421
 422     # optional method for 'global' loading
 423     sub dl_load_flags { 0x01 }
 424
 425
 426 =head1 DESCRIPTION
 427
 428 This document defines a standard generic interface to the dynamic
 429 linking mechanisms available on many platforms.  Its primary purpose is
 430 to implement automatic dynamic loading of Perl modules.
 431
 432 This document serves as both a specification for anyone wishing to
 433 implement the DynaLoader for a new platform and as a guide for
 434 anyone wishing to use the DynaLoader directly in an application.
 435
 436 The DynaLoader is designed to be a very simple high-level
 437 interface that is sufficiently general to cover the requirements
 438 of SunOS, HP-UX, NeXT, Linux, VMS and other platforms.
 439
 440 It is also hoped that the interface will cover the needs of OS/2, NT
 441 etc and also allow pseudo-dynamic linking (using C<ld -A> at runtime).
 442
 443 It must be stressed that the DynaLoader, by itself, is practically
 444 useless for accessing non-Perl libraries because it provides almost no
 445 Perl-to-C 'glue'.  There is, for example, no mechanism for calling a C
 446 library function or supplying arguments.  A C::DynaLib module
 447 is available from CPAN sites which performs that function for some
 448 common system types.
 449
 450 DynaLoader Interface Summary
 451
 452   @dl_library_path
 453   @dl_resolve_using
 454   @dl_require_symbols
 455   $dl_debug
 456   @dl_librefs
 457   @dl_modules
 458                                                   Implemented in:
 459   bootstrap($modulename)                               Perl
 460   @filepaths = dl_findfile(@names)                     Perl
 461   $flags = $modulename->dl_load_flags                  Perl
 462   $symref  = dl_find_symbol_anywhere($symbol)          Perl
 463
 464   $libref  = dl_load_file($filename, $flags)           C
 465   $symref  = dl_find_symbol($libref, $symbol)          C
 466   @symbols = dl_undef_symbols()                        C
 467   dl_install_xsub($name, $symref [, $filename])        C
 468   $message = dl_error                                  C
 469
 470 =over 4
 471
 472 =item @dl_library_path
 473
 474 The standard/default list of directories in which dl_findfile() will
 475 search for libraries etc.  Directories are searched in order:
 476 $dl_library_path[0], [1], ... etc
 477
 478 @dl_library_path is initialised to hold the list of 'normal' directories
 479 (F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}>).  This should
 480 ensure portability across a wide range of platforms.
 481
 482 @dl_library_path should also be initialised with any other directories
 483 that can be determined from the environment at runtime (such as
 484 LD_LIBRARY_PATH for SunOS).
 485
 486 After initialisation @dl_library_path can be manipulated by an
 487 application using push and unshift before calling dl_findfile().
 488 Unshift can be used to add directories to the front of the search order
 489 either to save search time or to override libraries with the same name
 490 in the 'normal' directories.
 491
 492 The load function that dl_load_file() calls may require an absolute
 493 pathname.  The dl_findfile() function and @dl_library_path can be
 494 used to search for and return the absolute pathname for the
 495 library/object that you wish to load.
 496
 497 =item @dl_resolve_using
 498
 499 A list of additional libraries or other shared objects which can be
 500 used to resolve any undefined symbols that might be generated by a
 501 later call to load_file().
 502
 503 This is only required on some platforms which do not handle dependent
 504 libraries automatically.  For example the Socket Perl extension
 505 library (F<auto/Socket/Socket.so>) contains references to many socket
 506 functions which need to be resolved when it's loaded.  Most platforms
 507 will automatically know where to find the 'dependent' library (e.g.,
 508 F</usr/lib/libsocket.so>).  A few platforms need to be told the
 509 location of the dependent library explicitly.  Use @dl_resolve_using
 510 for this.
 511
 512 Example usage:
 513
 514     @dl_resolve_using = dl_findfile('-lsocket');
 515
 516 =item @dl_require_symbols
 517
 518 A list of one or more symbol names that are in the library/object file
 519 to be dynamically loaded.  This is only required on some platforms.
 520
 521 =item @dl_librefs
 522
 523 An array of the handles returned by successful calls to dl_load_file(),
 524 made by bootstrap, in the order in which they were loaded.
 525 Can be used with dl_find_symbol() to look for a symbol in any of
 526 the loaded files.
 527
 528 =item @dl_modules
 529
 530 An array of module (package) names that have been bootstrap'ed.
 531
 532 =item dl_error()
 533
 534 Syntax:
 535
 536     $message = dl_error();
 537
 538 Error message text from the last failed DynaLoader function.  Note
 539 that, similar to errno in unix, a successful function call does not
 540 reset this message.
 541
 542 Implementations should detect the error as soon as it occurs in any of
 543 the other functions and save the corresponding message for later
 544 retrieval.  This will avoid problems on some platforms (such as SunOS)
 545 where the error message is very temporary (e.g., dlerror()).
 546
 547 =item $dl_debug
 548
 549 Internal debugging messages are enabled when $dl_debug is set true.
 550 Currently setting $dl_debug only affects the Perl side of the
 551 DynaLoader.  These messages should help an application developer to
 552 resolve any DynaLoader usage problems.
 553
 554 $dl_debug is set to C<$ENV{'PERL_DL_DEBUG'}> if defined.
 555
 556 For the DynaLoader developer/porter there is a similar debugging
 557 variable added to the C code (see dlutils.c) and enabled if Perl was
 558 built with the B<-DDEBUGGING> flag.  This can also be set via the
 559 PERL_DL_DEBUG environment variable.  Set to 1 for minimal information or
 560 higher for more.
 561
 562 =item dl_findfile()
 563
 564 Syntax:
 565
 566     @filepaths = dl_findfile(@names)
 567
 568 Determine the full paths (including file suffix) of one or more
 569 loadable files given their generic names and optionally one or more
 570 directories.  Searches directories in @dl_library_path by default and
 571 returns an empty list if no files were found.
 572
 573 Names can be specified in a variety of platform independent forms.  Any
 574 names in the form B<-lname> are converted into F<libname.*>, where F<.*> is
 575 an appropriate suffix for the platform.
 576
 577 If a name does not already have a suitable prefix and/or suffix then
 578 the corresponding file will be searched for by trying combinations of
 579 prefix and suffix appropriate to the platform: "$name.o", "lib$name.*"
 580 and "$name".
 581
 582 If any directories are included in @names they are searched before
 583 @dl_library_path.  Directories may be specified as B<-Ldir>.  Any other
 584 names are treated as filenames to be searched for.
 585
 586 Using arguments of the form C<-Ldir> and C<-lname> is recommended.
 587
 588 Example:
 589
 590     @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));
 591
 592
 593 =item dl_expandspec()
 594
 595 Syntax:
 596
 597     $filepath = dl_expandspec($spec)
 598
 599 Some unusual systems, such as VMS, require special filename handling in
 600 order to deal with symbolic names for files (i.e., VMS's Logical Names).
 601
 602 To support these systems a dl_expandspec() function can be implemented
 603 either in the F<dl_*.xs> file or code can be added to the autoloadable
 604 dl_expandspec() function in F<DynaLoader.pm>.  See F<DynaLoader.pm> for
 605 more information.
 606
 607 =item dl_load_file()
 608
 609 Syntax:
 610
 611     $libref = dl_load_file($filename, $flags)
 612
 613 Dynamically load $filename, which must be the path to a shared object
 614 or library.  An opaque 'library reference' is returned as a handle for
 615 the loaded object.  Returns undef on error.
 616
 617 The $flags argument to alters dl_load_file behaviour.
 618 Assigned bits:
 619
 620  0x01  make symbols available for linking later dl_load_file's.
 621        (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
 622        (ignored under VMS; this is a normal part of image linking)
 623
 624 (On systems that provide a handle for the loaded object such as SunOS
 625 and HPUX, $libref will be that handle.  On other systems $libref will
 626 typically be $filename or a pointer to a buffer containing $filename.
 627 The application should not examine or alter $libref in any way.)
 628
 629 This is the function that does the real work.  It should use the
 630 current values of @dl_require_symbols and @dl_resolve_using if required.
 631
 632     SunOS: dlopen($filename)
 633     HP-UX: shl_load($filename)
 634     Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
 635     NeXT:  rld_load($filename, @dl_resolve_using)
 636     VMS:   lib$find_image_symbol($filename,$dl_require_symbols[0])
 637
 638 (The dlopen() function is also used by Solaris and some versions of
 639 Linux, and is a common choice when providing a "wrapper" on other
 640 mechanisms as is done in the OS/2 port.)
 641
 642 =item dl_loadflags()
 643
 644 Syntax:
 645
 646     $flags = dl_loadflags $modulename;
 647
 648 Designed to be a method call, and to be overridden by a derived class
 649 (i.e. a class which has DynaLoader in its @ISA).  The definition in
 650 DynaLoader itself returns 0, which produces standard behavior from
 651 dl_load_file().
 652
 653 =item dl_find_symbol()
 654
 655 Syntax:
 656
 657     $symref = dl_find_symbol($libref, $symbol)
 658
 659 Return the address of the symbol $symbol or C<undef> if not found.  If the
 660 target system has separate functions to search for symbols of different
 661 types then dl_find_symbol() should search for function symbols first and
 662 then other types.
 663
 664 The exact manner in which the address is returned in $symref is not
 665 currently defined.  The only initial requirement is that $symref can
 666 be passed to, and understood by, dl_install_xsub().
 667
 668     SunOS: dlsym($libref, $symbol)
 669     HP-UX: shl_findsym($libref, $symbol)
 670     Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
 671     NeXT:  rld_lookup("_$symbol")
 672     VMS:   lib$find_image_symbol($libref,$symbol)
 673
 674
 675 =item dl_find_symbol_anywhere()
 676
 677 Syntax:
 678
 679     $symref = dl_find_symbol_anywhere($symbol)
 680
 681 Applies dl_find_symbol() to the members of @dl_librefs and returns
 682 the first match found.
 683
 684 =item dl_undef_symbols()
 685
 686 Example
 687
 688     @symbols = dl_undef_symbols()
 689
 690 Return a list of symbol names which remain undefined after load_file().
 691 Returns C<()> if not known.  Don't worry if your platform does not provide
 692 a mechanism for this.  Most do not need it and hence do not provide it,
 693 they just return an empty list.
 694
 695
 696 =item dl_install_xsub()
 697
 698 Syntax:
 699
 700     dl_install_xsub($perl_name, $symref [, $filename])
 701
 702 Create a new Perl external subroutine named $perl_name using $symref as
 703 a pointer to the function which implements the routine.  This is simply
 704 a direct call to newXSUB().  Returns a reference to the installed
 705 function.
 706
 707 The $filename parameter is used by Perl to identify the source file for
 708 the function if required by die(), caller() or the debugger.  If
 709 $filename is not defined then "DynaLoader" will be used.
 710
 711
 712 =item bootstrap()
 713
 714 Syntax:
 715
 716 bootstrap($module)
 717
 718 This is the normal entry point for automatic dynamic loading in Perl.
 719
 720 It performs the following actions:
 721
 722 =over 8
 723
 724 =item *
 725
 726 locates an auto/$module directory by searching @INC
 727
 728 =item *
 729
 730 uses dl_findfile() to determine the filename to load
 731
 732 =item *
 733
 734 sets @dl_require_symbols to C<("boot_$module")>
 735
 736 =item *
 737
 738 executes an F<auto/$module/$module.bs> file if it exists
 739 (typically used to add to @dl_resolve_using any files which
 740 are required to load the module on the current platform)
 741
 742 =item *
 743
 744 calls dl_load_flags() to determine how to load the file.
 745
 746 =item *
 747
 748 calls dl_load_file() to load the file
 749
 750 =item *
 751
 752 calls dl_undef_symbols() and warns if any symbols are undefined
 753
 754 =item *
 755
 756 calls dl_find_symbol() for "boot_$module"
 757
 758 =item *
 759
 760 calls dl_install_xsub() to install it as "${module}::bootstrap"
 761
 762 =item *
 763
 764 calls &{"${module}::bootstrap"} to bootstrap the module (actually
 765 it uses the function reference returned by dl_install_xsub for speed)
 766
 767 =back
 768
 769 =back
 770
 771
 772 =head1 AUTHOR
 773
 774 Tim Bunce, 11 August 1994.
 775
 776 This interface is based on the work and comments of (in no particular
 777 order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
 778 Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and others.
 779
 780 Larry Wall designed the elegant inherited bootstrap mechanism and
 781 implemented the first Perl 5 dynamic loader using it.
 782
 783 Solaris global loading added by Nick Ing-Simmons with design/coding
 784 assistance from Tim Bunce, January 1996.
 785
 786 =cut
 787 EOT
 788
 789 close OUT or die $!;
 790