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
8 # (Quote from Tolkien sugested by Anno Siegel.)
10 # See pod text at end of file for documentation.
11 # See also ext/DynaLoader/README in source tree for other information.
13 # Tim.Bunce@ig.co.uk, August 1994
15 use vars qw($VERSION @ISA) ;
25 sub import { } # override import inherited from AutoLoader
27 # enable debug/trace messages from DynaLoader perl code
28 $dl_debug = $ENV{PERL_DL_DEBUG} || 0 unless defined $dl_debug;
31 # Flags to alter dl_load_file behaviour. Assigned bits:
32 # 0x01 make symbols available for linking later dl_load_file's.
33 # (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
34 # (ignored under VMS; effect is built-in to image linking)
36 # This is called as a class method $module->dl_load_flags. The
37 # definition here will be inherited and result on "default" loading
38 # behaviour unless a sub-class of DynaLoader defines its own version.
41 sub dl_load_flags { 0x00 }
46 = @Config::Config{'dlext', 'dlsrc'};
48 # Some systems need special handling to expand file specifications
49 # (VMS support by Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>)
50 # See dl_expandspec() for more details. Should be harmless but
51 # inefficient to define on systems that don't need it.
52 $do_expand = $Is_VMS = $^O eq 'VMS';
54 @dl_require_symbols = (); # names of symbols we need
55 @dl_resolve_using = (); # names of files to link with
56 @dl_library_path = (); # path to look for files
57 @dl_librefs = (); # things we have loaded
58 @dl_modules = (); # Modules we have loaded
60 # This is a fix to support DLD's unfortunate desire to relink -lc
61 @dl_resolve_using = dl_findfile('-lc') if $dlsrc eq "dl_dld.xs";
63 # Initialise @dl_library_path with the 'standard' library path
64 # for this platform as determined by Configure
65 push(@dl_library_path, split(' ',$Config::Config{'libpth'}));
67 # Add to @dl_library_path any extra directories we can gather from
68 # environment variables. So far LD_LIBRARY_PATH is the only known
69 # variable used for this purpose. Others may be added later.
70 push(@dl_library_path, split(/:/, $ENV{LD_LIBRARY_PATH}))
71 if $ENV{LD_LIBRARY_PATH};
74 # No prizes for guessing why we don't say 'bootstrap DynaLoader;' here.
75 boot_DynaLoader('DynaLoader') if defined(&boot_DynaLoader);
79 print STDERR "DynaLoader.pm loaded (@INC, @dl_library_path)\n";
80 print STDERR "DynaLoader not linked into this perl\n"
81 unless defined(&boot_DynaLoader);
87 # The bootstrap function cannot be autoloaded (without complications)
88 # so we define it here:
91 # use local vars to enable $module.bs script to edit values
93 local($module) = $args[0];
96 Carp::confess("Usage: DynaLoader::bootstrap(module)") unless $module;
98 # A common error on platforms which don't support dynamic loading.
99 # Since it's fatal and potentially confusing we give a detailed message.
100 Carp::croak("Can't load module $module, dynamic loading not available in this perl.\n".
101 " (You may need to build a new perl executable which either supports\n".
102 " dynamic loading or has the $module module statically linked into it.)\n")
103 unless defined(&dl_load_file);
105 my @modparts = split(/::/,$module);
106 my $modfname = $modparts[-1];
108 # Some systems have restrictions on files names for DLL's etc.
109 # mod2fname returns appropriate file base name (typically truncated)
110 # It may also edit @modparts if required.
111 $modfname = &mod2fname(\@modparts) if defined &mod2fname;
113 my $modpname = join('/',@modparts);
115 print STDERR "DynaLoader::bootstrap for $module ",
116 "(auto/$modpname/$modfname.$dl_dlext)\n" if $dl_debug;
119 chop($_ = VMS::Filespec::unixpath($_)) if $Is_VMS;
120 my $dir = "$_/auto/$modpname";
121 next unless -d $dir; # skip over uninteresting directories
123 # check for common cases to avoid autoload of dl_findfile
124 last if ($file=_check_file("$dir/$modfname.$dl_dlext"));
126 # no luck here, save dir for possible later dl_findfile search
127 push(@dirs, "-L$dir");
129 # last resort, let dl_findfile have a go in all known locations
130 $file = dl_findfile(@dirs, map("-L$_",@INC), $modfname) unless $file;
132 Carp::croak("Can't find loadable object for module $module in \@INC (@INC)")
135 my $bootname = "boot_$module";
136 $bootname =~ s/\W/_/g;
137 @dl_require_symbols = ($bootname);
139 # Execute optional '.bootstrap' perl script for this module.
140 # The .bs file can be used to configure @dl_resolve_using etc to
141 # match the needs of the individual module on this architecture.
143 $bs =~ s/(\.\w+)?$/\.bs/; # look for .bs 'beside' the library
144 if (-s $bs) { # only read file if it's not empty
145 print STDERR "BS: $bs ($^O, $dlsrc)\n" if $dl_debug;
147 warn "$bs: $@\n" if $@;
150 # Many dynamic extension loading problems will appear to come from
151 # this section of code: XYZ failed at line 123 of DynaLoader.pm.
152 # Often these errors are actually occurring in the initialisation
153 # C code of the extension XS file. Perl reports the error as being
154 # in this perl code simply because this was the last perl code
157 my $libref = dl_load_file($file, $module->dl_load_flags) or
158 Carp::croak("Can't load '$file' for module $module: ".dl_error()."\n");
160 push(@dl_librefs,$libref); # record loaded object
162 my @unresolved = dl_undef_symbols();
163 Carp::carp("Undefined symbols present after loading $file: @unresolved\n")
166 my $boot_symbol_ref = dl_find_symbol($libref, $bootname) or
167 Carp::croak("Can't find '$bootname' symbol in $file\n");
169 my $xs = dl_install_xsub("${module}::bootstrap", $boot_symbol_ref, $file);
171 push(@dl_modules, $module); # record loaded module
173 # See comment block above
178 sub _check_file { # private utility to handle dl_expandspec vs -f tests
180 return $file if (!$do_expand && -f $file); # the common case
181 return $file if ( $do_expand && ($file=dl_expandspec($file)));
186 # Let autosplit and the autoloader deal with these functions:
191 # Read ext/DynaLoader/DynaLoader.doc for detailed information.
192 # This function does not automatically consider the architecture
193 # or the perl library auto directories.
195 my (@dirs, $dir); # which directories to search
196 my (@found); # full paths to real files we have found
197 my $dl_ext= $Config::Config{'dlext'}; # suffix for perl extensions
198 my $dl_so = $Config::Config{'so'}; # suffix for shared libraries
200 print STDERR "dl_findfile(@args)\n" if $dl_debug;
202 # accumulate directories but process files as they appear
203 arg: foreach(@args) {
204 # Special fast case: full filepath requires no search
205 if ($Is_VMS && m%[:>/\]]% && -f $_) {
206 push(@found,dl_expandspec(VMS::Filespec::vmsify($_)));
207 last arg unless wantarray;
210 elsif (m:/: && -f $_ && !$do_expand) {
212 last arg unless wantarray;
216 # Deal with directories first:
217 # Using a -L prefix is the preferred option (faster and more robust)
218 if (m:^-L:) { s/^-L//; push(@dirs, $_); next; }
220 # Otherwise we try to try to spot directories by a heuristic
221 # (this is a more complicated issue than it first appears)
222 if (m:/: && -d $_) { push(@dirs, $_); next; }
224 # VMS: we may be using native VMS directry syntax instead of
225 # Unix emulation, so check this as well
226 if ($Is_VMS && /[:>\]]/ && -d $_) { push(@dirs, $_); next; }
228 # Only files should get this far...
229 my(@names, $name); # what filenames to look for
230 if (m:-l: ) { # convert -lname to appropriate library name
232 push(@names,"lib$_.$dl_so");
233 push(@names,"lib$_.a");
234 } else { # Umm, a bare name. Try various alternatives:
235 # these should be ordered with the most likely first
236 push(@names,"$_.$dl_ext") unless m/\.$dl_ext$/o;
237 push(@names,"$_.$dl_so") unless m/\.$dl_so$/o;
238 push(@names,"lib$_.$dl_so") unless m:/:;
239 push(@names,"$_.a") if !m/\.a$/ and $dlsrc eq "dl_dld.xs";
242 foreach $dir (@dirs, @dl_library_path) {
244 chop($dir = VMS::Filespec::unixpath($dir)) if $Is_VMS;
245 foreach $name (@names) {
246 my($file) = "$dir/$name";
247 print STDERR " checking in $dir for $name\n" if $dl_debug;
248 $file = _check_file($file);
251 next arg; # no need to look any further
258 print STDERR " dl_findfile ignored non-existent directory: $_\n" unless -d $_;
260 print STDERR "dl_findfile found: @found\n";
262 return $found[0] unless wantarray;
269 # Optional function invoked if DynaLoader.pm sets $do_expand.
270 # Most systems do not require or use this function.
271 # Some systems may implement it in the dl_*.xs file in which case
272 # this autoload version will not be called but is harmless.
274 # This function is designed to deal with systems which treat some
275 # 'filenames' in a special way. For example VMS 'Logical Names'
276 # (something like unix environment variables - but different).
277 # This function should recognise such names and expand them into
279 # Must return undef if $spec is invalid or file does not exist.
281 my $file = $spec; # default output to input
283 if ($Is_VMS) { # dl_expandspec should be defined in dl_vms.xs
284 Carp::croak("dl_expandspec: should be defined in XS file!\n");
286 return undef unless -f $file;
288 print STDERR "dl_expandspec($spec) => $file\n" if $dl_debug;
292 sub dl_find_symbol_anywhere
296 foreach $libref (@dl_librefs) {
297 my $symref = dl_find_symbol($libref,$sym);
298 return $symref if $symref;
305 DynaLoader - Dynamically load C libraries into Perl code
307 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
313 @ISA = qw(... DynaLoader ...);
314 bootstrap YourPackage;
316 # optional method for 'global' loading
317 sub dl_load_flags { 0x01 }
322 This document defines a standard generic interface to the dynamic
323 linking mechanisms available on many platforms. Its primary purpose is
324 to implement automatic dynamic loading of Perl modules.
326 This document serves as both a specification for anyone wishing to
327 implement the DynaLoader for a new platform and as a guide for
328 anyone wishing to use the DynaLoader directly in an application.
330 The DynaLoader is designed to be a very simple high-level
331 interface that is sufficiently general to cover the requirements
332 of SunOS, HP-UX, NeXT, Linux, VMS and other platforms.
334 It is also hoped that the interface will cover the needs of OS/2, NT
335 etc and also allow pseudo-dynamic linking (using C<ld -A> at runtime).
337 It must be stressed that the DynaLoader, by itself, is practically
338 useless for accessing non-Perl libraries because it provides almost no
339 Perl-to-C 'glue'. There is, for example, no mechanism for calling a C
340 library function or supplying arguments. It is anticipated that any
341 glue that may be developed in the future will be implemented in a
342 separate dynamically loaded module.
344 DynaLoader Interface Summary
353 bootstrap($modulename) Perl
354 @filepaths = dl_findfile(@names) Perl
355 $flags = $modulename->dl_load_flags Perl
356 $symref = dl_find_symbol_anywhere($symbol) Perl
358 $libref = dl_load_file($filename, $flags) C
359 $symref = dl_find_symbol($libref, $symbol) C
360 @symbols = dl_undef_symbols() C
361 dl_install_xsub($name, $symref [, $filename]) C
362 $message = dl_error C
366 =item @dl_library_path
368 The standard/default list of directories in which dl_findfile() will
369 search for libraries etc. Directories are searched in order:
370 $dl_library_path[0], [1], ... etc
372 @dl_library_path is initialised to hold the list of 'normal' directories
373 (F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}>). This should
374 ensure portability across a wide range of platforms.
376 @dl_library_path should also be initialised with any other directories
377 that can be determined from the environment at runtime (such as
378 LD_LIBRARY_PATH for SunOS).
380 After initialisation @dl_library_path can be manipulated by an
381 application using push and unshift before calling dl_findfile().
382 Unshift can be used to add directories to the front of the search order
383 either to save search time or to override libraries with the same name
384 in the 'normal' directories.
386 The load function that dl_load_file() calls may require an absolute
387 pathname. The dl_findfile() function and @dl_library_path can be
388 used to search for and return the absolute pathname for the
389 library/object that you wish to load.
391 =item @dl_resolve_using
393 A list of additional libraries or other shared objects which can be
394 used to resolve any undefined symbols that might be generated by a
395 later call to load_file().
397 This is only required on some platforms which do not handle dependent
398 libraries automatically. For example the Socket Perl extension library
399 (F<auto/Socket/Socket.so>) contains references to many socket functions
400 which need to be resolved when it's loaded. Most platforms will
401 automatically know where to find the 'dependent' library (e.g.,
402 F</usr/lib/libsocket.so>). A few platforms need to to be told the location
403 of the dependent library explicitly. Use @dl_resolve_using for this.
407 @dl_resolve_using = dl_findfile('-lsocket');
409 =item @dl_require_symbols
411 A list of one or more symbol names that are in the library/object file
412 to be dynamically loaded. This is only required on some platforms.
416 An array of the handles returned by successful calls to dl_load_file(),
417 made by bootstrap, in the order in which they were loaded.
418 Can be used with dl_find_symbol() to look for a symbol in any of
423 An array of module (package) names that have been bootstrap'ed.
429 $message = dl_error();
431 Error message text from the last failed DynaLoader function. Note
432 that, similar to errno in unix, a successful function call does not
435 Implementations should detect the error as soon as it occurs in any of
436 the other functions and save the corresponding message for later
437 retrieval. This will avoid problems on some platforms (such as SunOS)
438 where the error message is very temporary (e.g., dlerror()).
442 Internal debugging messages are enabled when $dl_debug is set true.
443 Currently setting $dl_debug only affects the Perl side of the
444 DynaLoader. These messages should help an application developer to
445 resolve any DynaLoader usage problems.
447 $dl_debug is set to C<$ENV{'PERL_DL_DEBUG'}> if defined.
449 For the DynaLoader developer/porter there is a similar debugging
450 variable added to the C code (see dlutils.c) and enabled if Perl was
451 built with the B<-DDEBUGGING> flag. This can also be set via the
452 PERL_DL_DEBUG environment variable. Set to 1 for minimal information or
459 @filepaths = dl_findfile(@names)
461 Determine the full paths (including file suffix) of one or more
462 loadable files given their generic names and optionally one or more
463 directories. Searches directories in @dl_library_path by default and
464 returns an empty list if no files were found.
466 Names can be specified in a variety of platform independent forms. Any
467 names in the form B<-lname> are converted into F<libname.*>, where F<.*> is
468 an appropriate suffix for the platform.
470 If a name does not already have a suitable prefix and/or suffix then
471 the corresponding file will be searched for by trying combinations of
472 prefix and suffix appropriate to the platform: "$name.o", "lib$name.*"
475 If any directories are included in @names they are searched before
476 @dl_library_path. Directories may be specified as B<-Ldir>. Any other
477 names are treated as filenames to be searched for.
479 Using arguments of the form C<-Ldir> and C<-lname> is recommended.
483 @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));
486 =item dl_expandspec()
490 $filepath = dl_expandspec($spec)
492 Some unusual systems, such as VMS, require special filename handling in
493 order to deal with symbolic names for files (i.e., VMS's Logical Names).
495 To support these systems a dl_expandspec() function can be implemented
496 either in the F<dl_*.xs> file or code can be added to the autoloadable
497 dl_expandspec() function in F<DynaLoader.pm>. See F<DynaLoader.pm> for
504 $libref = dl_load_file($filename, $flags)
506 Dynamically load $filename, which must be the path to a shared object
507 or library. An opaque 'library reference' is returned as a handle for
508 the loaded object. Returns undef on error.
510 The $flags argument to alters dl_load_file behaviour.
513 0x01 make symbols available for linking later dl_load_file's.
514 (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
515 (ignored under VMS; this is a normal part of image linking)
517 (On systems that provide a handle for the loaded object such as SunOS
518 and HPUX, $libref will be that handle. On other systems $libref will
519 typically be $filename or a pointer to a buffer containing $filename.
520 The application should not examine or alter $libref in any way.)
522 This is the function that does the real work. It should use the
523 current values of @dl_require_symbols and @dl_resolve_using if required.
525 SunOS: dlopen($filename)
526 HP-UX: shl_load($filename)
527 Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
528 NeXT: rld_load($filename, @dl_resolve_using)
529 VMS: lib$find_image_symbol($filename,$dl_require_symbols[0])
531 (The dlopen() function is also used by Solaris and some versions of
532 Linux, and is a common choice when providing a "wrapper" on other
533 mechanisms as is done in the OS/2 port.)
539 $flags = dl_loadflags $modulename;
541 Designed to be a method call, and to be overridden by a derived class
542 (i.e. a class which has DynaLoader in its @ISA). The definition in
543 DynaLoader itself returns 0, which produces standard behavior from
546 =item dl_find_symbol()
550 $symref = dl_find_symbol($libref, $symbol)
552 Return the address of the symbol $symbol or C<undef> if not found. If the
553 target system has separate functions to search for symbols of different
554 types then dl_find_symbol() should search for function symbols first and
557 The exact manner in which the address is returned in $symref is not
558 currently defined. The only initial requirement is that $symref can
559 be passed to, and understood by, dl_install_xsub().
561 SunOS: dlsym($libref, $symbol)
562 HP-UX: shl_findsym($libref, $symbol)
563 Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
564 NeXT: rld_lookup("_$symbol")
565 VMS: lib$find_image_symbol($libref,$symbol)
568 =item dl_find_symbol_anywhere()
572 $symref = dl_find_symbol_anywhere($symbol)
574 Applies dl_find_symbol() to the members of @dl_librefs and returns
575 the first match found.
577 =item dl_undef_symbols()
581 @symbols = dl_undef_symbols()
583 Return a list of symbol names which remain undefined after load_file().
584 Returns C<()> if not known. Don't worry if your platform does not provide
585 a mechanism for this. Most do not need it and hence do not provide it,
586 they just return an empty list.
589 =item dl_install_xsub()
593 dl_install_xsub($perl_name, $symref [, $filename])
595 Create a new Perl external subroutine named $perl_name using $symref as
596 a pointer to the function which implements the routine. This is simply
597 a direct call to newXSUB(). Returns a reference to the installed
600 The $filename parameter is used by Perl to identify the source file for
601 the function if required by die(), caller() or the debugger. If
602 $filename is not defined then "DynaLoader" will be used.
611 This is the normal entry point for automatic dynamic loading in Perl.
613 It performs the following actions:
619 locates an auto/$module directory by searching @INC
623 uses dl_findfile() to determine the filename to load
627 sets @dl_require_symbols to C<("boot_$module")>
631 executes an F<auto/$module/$module.bs> file if it exists
632 (typically used to add to @dl_resolve_using any files which
633 are required to load the module on the current platform)
637 calls dl_load_flags() to determine how to load the file.
641 calls dl_load_file() to load the file
645 calls dl_undef_symbols() and warns if any symbols are undefined
649 calls dl_find_symbol() for "boot_$module"
653 calls dl_install_xsub() to install it as "${module}::bootstrap"
657 calls &{"${module}::bootstrap"} to bootstrap the module (actually
658 it uses the function reference returned by dl_install_xsub for speed)
667 Tim Bunce, 11 August 1994.
669 This interface is based on the work and comments of (in no particular
670 order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
671 Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and others.
673 Larry Wall designed the elegant inherited bootstrap mechanism and
674 implemented the first Perl 5 dynamic loader using it.
676 Solaris global loading added by Nick Ing-Simmons with design/coding
677 assistance from Tim Bunce, January 1996.