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