"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/lib/DynaLoader.pm" (10 Mar 2019, 25180 Bytes) of package /windows/misc/install-tl.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

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