ext/DynaLoader/DynaLoader.pm

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