← Index
NYTProf Performance Profile   « block view • line view • sub view »
For ddd2.pl
  Run on Tue May 25 16:52:24 2010
Reported on Tue May 25 16:56:49 2010

File /usr/local/lib/perl5/5.8.8/i686-linux/DynaLoader.pm
Statements Executed 270
Statement Execution Time 46.5ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time		 Inclusive
Time		 Subroutine
61236.0ms36.0msDynaLoader::::CORE:ftsizeDynaLoader::CORE:ftsize (opcode)
6662.47ms43.1msDynaLoader::::bootstrapDynaLoader::bootstrap
6122.01ms2.01msDynaLoader::::dl_load_fileDynaLoader::dl_load_file (xsub)
612525µs525µsDynaLoader::::dl_install_xsubDynaLoader::dl_install_xsub (xsub)
1222281µs281µsDynaLoader::::CORE:substDynaLoader::CORE:subst (opcode)
612190µs190µsDynaLoader::::CORE:ftdirDynaLoader::CORE:ftdir (opcode)
61193µs93µsDynaLoader::::dl_load_flagsDynaLoader::dl_load_flags
61282µs82µsDynaLoader::::CORE:ftfileDynaLoader::CORE:ftfile (opcode)
61260µs60µsDynaLoader::::dl_find_symbolDynaLoader::dl_find_symbol (xsub)
61246µs46µsDynaLoader::::dl_undef_symbolsDynaLoader::dl_undef_symbols (xsub)
0000s0sDynaLoader::::BEGINDynaLoader::BEGIN
0000s0sDynaLoader::::bootstrap_inheritDynaLoader::bootstrap_inherit
0000s0sDynaLoader::::croakDynaLoader::croak
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments		 Time
on line		 Calls Time
in subs		 Code
1
2# Generated from DynaLoader.pm.PL
3
4package 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
183150µs1236µsuse vars qw($VERSION *AUTOLOAD);
# spent 236µs making 1 call to vars::import
19
2016µs$VERSION = '1.05'; # avoid typo warning
21
221264µsrequire AutoLoader;
23124µs*AUTOLOAD = \&AutoLoader::AUTOLOAD;
24
2532.60ms172µsuse Config;
# spent 72µs making 1 call to Config::import
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.
3217µsrequire Carp if $] < 5.00450;
33
34# enable debug/trace messages from DynaLoader perl code
3519µs$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
48696µs
# spent 93µs within DynaLoader::dl_load_flags which was called 6 times, avg 16µs/call: # 6 times (93µs+0s) by DynaLoader::bootstrap at line 230, avg 16µs/call
sub dl_load_flags { 0x00 }
49
50# ($dl_dlext, $dlsrc)
51# = @Config::Config{'dlext', 'dlsrc'};
5217µs ($dl_dlext, $dlsrc) = ('so','dl_dlopen.xs')
53;
54# Some systems need special handling to expand file specifications
55# (VMS support by Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>)
56# See dl_expandspec() for more details. Should be harmless but
57# inefficient to define on systems that don't need it.
5819µs$Is_VMS = $^O eq 'VMS';
5915µs$do_expand = $Is_VMS;
6015µs$Is_MacOS = $^O eq 'MacOS';
61
6215µsmy $Mac_FS;
6314µs$Mac_FS = eval { require Mac::FileSpec::Unixish } if $Is_MacOS;
64
6517µs@dl_require_symbols = (); # names of symbols we need
6615µs@dl_resolve_using = (); # names of files to link with
6715µs@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
7515µs@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
80140µs126µspush(@dl_library_path, split(' ', $Config::Config{libpth}));
# spent 26µs making 1 call to Config::FETCH
81
82
83123µs118µsmy $ldlibpthname = $Config::Config{ldlibpthname};
# spent 18µs making 1 call to Config::FETCH
84122µs117µsmy $ldlibpthname_defined = defined $Config::Config{ldlibpthname};
# spent 17µs making 1 call to Config::FETCH
85123µs118µsmy $pthsep = $Config::Config{path_sep};
# spent 18µs making 1 call to Config::FETCH
86
87# Add to @dl_library_path any extra directories we can gather from environment
88# during runtime.
89
9016µsif ($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
9715µsif ($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
10617µsboot_DynaLoader('DynaLoader') if defined(&boot_DynaLoader) &&
107 !defined(&dl_error);
108
10914µsif ($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
115152µs1; # End of main code
116
117
118sub croak { require Carp; Carp::croak(@_) }
119
120sub 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
# spent 43.1ms (2.47+40.7) within DynaLoader::bootstrap which was called 6 times, avg 7.19ms/call: # once (404µs+27.3ms) by Class::DBI::_require_class at line 38 of Class/Date.pm # once (414µs+10.2ms) by base::import at line 21 of Clone.pm # once (388µs+1.46ms) by DBI::install_driver at line 73 of DBD/Pg.pm # once (463µs+850µs) by base::import at line 254 of DBI.pm # once (387µs+492µs) by base::import at line 67 of Storable.pm # once (411µs+400µs) by base::import at line 17 of version/vxs.pm
sub bootstrap {
132 # use local vars to enable $module.bs script to edit values
13319242.3ms 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) {
17136689µs chop($_ = VMS::Filespec::unixpath($_)) if $Is_VMS;
172 my $dir;
173645µs 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
# spent 190µs making 6 calls to DynaLoader::CORE:ftdir, avg 32µs/call
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);
# spent 82µs making 6 calls to DynaLoader::CORE:ftfile, avg 14µs/call
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;
# spent 56µs making 6 calls to DynaLoader::CORE:subst, avg 9µs/call
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
# spent 225µs making 6 calls to DynaLoader::CORE:subst, avg 38µs/call
209 if (-s $bs) { # only read file if it's not empty
# spent 36.0ms making 6 calls to DynaLoader::CORE:ftsize, avg 6.00ms/call
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
# spent 2.01ms making 6 calls to DynaLoader::dl_load_file, avg 335µs/call # spent 93µs making 6 calls to DynaLoader::dl_load_flags, avg 16µs/call
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();
# spent 46µs making 6 calls to DynaLoader::dl_undef_symbols, avg 8µs/call
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
# spent 60µs making 6 calls to DynaLoader::dl_find_symbol, avg 10µs/call
242 croak("Can't find '$bootname' symbol in $file\n");
243
244 push(@dl_modules, $module); # record loaded module
245
246 boot:
# spent 525µs making 6 calls to DynaLoader::dl_install_xsub, avg 88µs/call
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);
# spent 757µs making 1 call to DBD::Pg::bootstrap # spent 402µs making 1 call to DBI::bootstrap # spent 138µs making 1 call to Storable::bootstrap # spent 55µs making 1 call to version::vxs::bootstrap # spent 29µs making 1 call to Clone::bootstrap # spent 21µs making 1 call to Class::Date::bootstrap
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
269sub 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= 'so'; # $Config::Config{'dlext'} suffix for perl extensions
277 my $dl_so = 'so'; # $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
377sub 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
403sub 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
416DynaLoader - 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
431This document defines a standard generic interface to the dynamic
432linking mechanisms available on many platforms. Its primary purpose is
433to implement automatic dynamic loading of Perl modules.
434
435This document serves as both a specification for anyone wishing to
436implement the DynaLoader for a new platform and as a guide for
437anyone wishing to use the DynaLoader directly in an application.
438
439The DynaLoader is designed to be a very simple high-level
440interface that is sufficiently general to cover the requirements
441of SunOS, HP-UX, NeXT, Linux, VMS and other platforms.
442
443It is also hoped that the interface will cover the needs of OS/2, NT
444etc and also allow pseudo-dynamic linking (using C<ld -A> at runtime).
445
446It must be stressed that the DynaLoader, by itself, is practically
447useless for accessing non-Perl libraries because it provides almost no
448Perl-to-C 'glue'. There is, for example, no mechanism for calling a C
449library function or supplying arguments. A C::DynaLib module
450is available from CPAN sites which performs that function for some
451common system types. And since the year 2000, there's also Inline::C,
452a module that allows you to write Perl subroutines in C. Also available
453from your local CPAN site.
454
455DynaLoader 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
481The standard/default list of directories in which dl_findfile() will
482search 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
487ensure portability across a wide range of platforms.
488
489@dl_library_path should also be initialised with any other directories
490that can be determined from the environment at runtime (such as
491LD_LIBRARY_PATH for SunOS).
492
493After initialisation @dl_library_path can be manipulated by an
494application using push and unshift before calling dl_findfile().
495Unshift can be used to add directories to the front of the search order
496either to save search time or to override libraries with the same name
497in the 'normal' directories.
498
499The load function that dl_load_file() calls may require an absolute
500pathname. The dl_findfile() function and @dl_library_path can be
501used to search for and return the absolute pathname for the
502library/object that you wish to load.
503
504=item @dl_resolve_using
505
506A list of additional libraries or other shared objects which can be
507used to resolve any undefined symbols that might be generated by a
508later call to load_file().
509
510This is only required on some platforms which do not handle dependent
511libraries automatically. For example the Socket Perl extension
512library (F<auto/Socket/Socket.so>) contains references to many socket
513functions which need to be resolved when it's loaded. Most platforms
514will automatically know where to find the 'dependent' library (e.g.,
515F</usr/lib/libsocket.so>). A few platforms need to be told the
516location of the dependent library explicitly. Use @dl_resolve_using
517for this.
518
519Example usage:
520
521 @dl_resolve_using = dl_findfile('-lsocket');
522
523=item @dl_require_symbols
524
525A list of one or more symbol names that are in the library/object file
526to be dynamically loaded. This is only required on some platforms.
527
528=item @dl_librefs
529
530An array of the handles returned by successful calls to dl_load_file(),
531made by bootstrap, in the order in which they were loaded.
532Can be used with dl_find_symbol() to look for a symbol in any of
533the loaded files.
534
535=item @dl_modules
536
537An array of module (package) names that have been bootstrap'ed.
538
539=item @dl_shared_objects
540
541An array of file names for the shared objects that were loaded.
542
543=item dl_error()
544
545Syntax:
546
547 $message = dl_error();
548
549Error message text from the last failed DynaLoader function. Note
550that, similar to errno in unix, a successful function call does not
551reset this message.
552
553Implementations should detect the error as soon as it occurs in any of
554the other functions and save the corresponding message for later
555retrieval. This will avoid problems on some platforms (such as SunOS)
556where the error message is very temporary (e.g., dlerror()).
557
558=item $dl_debug
559
560Internal debugging messages are enabled when $dl_debug is set true.
561Currently setting $dl_debug only affects the Perl side of the
562DynaLoader. These messages should help an application developer to
563resolve any DynaLoader usage problems.
564
565$dl_debug is set to C<$ENV{'PERL_DL_DEBUG'}> if defined.
566
567For the DynaLoader developer/porter there is a similar debugging
568variable added to the C code (see dlutils.c) and enabled if Perl was
569built with the B<-DDEBUGGING> flag. This can also be set via the
570PERL_DL_DEBUG environment variable. Set to 1 for minimal information or
571higher for more.
572
573=item dl_findfile()
574
575Syntax:
576
577 @filepaths = dl_findfile(@names)
578
579Determine the full paths (including file suffix) of one or more
580loadable files given their generic names and optionally one or more
581directories. Searches directories in @dl_library_path by default and
582returns an empty list if no files were found.
583
584Names can be specified in a variety of platform independent forms. Any
585names in the form B<-lname> are converted into F<libname.*>, where F<.*> is
586an appropriate suffix for the platform.
587
588If a name does not already have a suitable prefix and/or suffix then
589the corresponding file will be searched for by trying combinations of
590prefix and suffix appropriate to the platform: "$name.o", "lib$name.*"
591and "$name".
592
593If any directories are included in @names they are searched before
594@dl_library_path. Directories may be specified as B<-Ldir>. Any other
595names are treated as filenames to be searched for.
596
597Using arguments of the form C<-Ldir> and C<-lname> is recommended.
598
599Example:
600
601 @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));
602
603
604=item dl_expandspec()
605
606Syntax:
607
608 $filepath = dl_expandspec($spec)
609
610Some unusual systems, such as VMS, require special filename handling in
611order to deal with symbolic names for files (i.e., VMS's Logical Names).
612
613To support these systems a dl_expandspec() function can be implemented
614either in the F<dl_*.xs> file or code can be added to the autoloadable
615dl_expandspec() function in F<DynaLoader.pm>. See F<DynaLoader.pm> for
616more information.
617
618=item dl_load_file()
619
620Syntax:
621
622 $libref = dl_load_file($filename, $flags)
623
624Dynamically load $filename, which must be the path to a shared object
625or library. An opaque 'library reference' is returned as a handle for
626the loaded object. Returns undef on error.
627
628The $flags argument to alters dl_load_file behaviour.
629Assigned 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
636and HPUX, $libref will be that handle. On other systems $libref will
637typically be $filename or a pointer to a buffer containing $filename.
638The application should not examine or alter $libref in any way.)
639
640This is the function that does the real work. It should use the
641current 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
650Linux, and is a common choice when providing a "wrapper" on other
651mechanisms as is done in the OS/2 port.)
652
653=item dl_unload_file()
654
655Syntax:
656
657 $status = dl_unload_file($libref)
658
659Dynamically unload $libref, which must be an opaque 'library reference' as
660returned from dl_load_file. Returns one on success and zero on failure.
661
662This function is optional and may not necessarily be provided on all platforms.
663If it is defined, it is called automatically when the interpreter exits for
664every shared object or library loaded by DynaLoader::bootstrap. All such
665library references are stored in @dl_librefs by DynaLoader::Bootstrap as it
666loads the libraries. The files are unloaded in last-in, first-out order.
667
668This unloading is usually necessary when embedding a shared-object perl (e.g.
669one configured with -Duseshrplib) within a larger application, and the perl
670interpreter is created and destroyed several times within the lifetime of the
671application. In this case it is possible that the system dynamic linker will
672unload and then subsequently reload the shared libperl without relocating any
673references to it from any files DynaLoaded by the previous incarnation of the
674interpreter. As a result, any shared objects opened by DynaLoader may point to
675a now invalid 'ghost' of the libperl shared object, causing apparently random
676memory corruption and crashes. This behaviour is most commonly seen when using
677Apache 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
686Linux, and is a common choice when providing a "wrapper" on other
687mechanisms as is done in the OS/2 port.)
688
689=item dl_load_flags()
690
691Syntax:
692
693 $flags = dl_load_flags $modulename;
694
695Designed 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
697DynaLoader itself returns 0, which produces standard behavior from
698dl_load_file().
699
700=item dl_find_symbol()
701
702Syntax:
703
704 $symref = dl_find_symbol($libref, $symbol)
705
706Return the address of the symbol $symbol or C<undef> if not found. If the
707target system has separate functions to search for symbols of different
708types then dl_find_symbol() should search for function symbols first and
709then other types.
710
711The exact manner in which the address is returned in $symref is not
712currently defined. The only initial requirement is that $symref can
713be 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
724Syntax:
725
726 $symref = dl_find_symbol_anywhere($symbol)
727
728Applies dl_find_symbol() to the members of @dl_librefs and returns
729the first match found.
730
731=item dl_undef_symbols()
732
733Example
734
735 @symbols = dl_undef_symbols()
736
737Return a list of symbol names which remain undefined after load_file().
738Returns C<()> if not known. Don't worry if your platform does not provide
739a mechanism for this. Most do not need it and hence do not provide it,
740they just return an empty list.
741
742
743=item dl_install_xsub()
744
745Syntax:
746
747 dl_install_xsub($perl_name, $symref [, $filename])
748
749Create a new Perl external subroutine named $perl_name using $symref as
750a pointer to the function which implements the routine. This is simply
751a direct call to newXSUB(). Returns a reference to the installed
752function.
753
754The $filename parameter is used by Perl to identify the source file for
755the 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
761Syntax:
762
763bootstrap($module)
764
765This is the normal entry point for automatic dynamic loading in Perl.
766
767It performs the following actions:
768
769=over 8
770
771=item *
772
773locates an auto/$module directory by searching @INC
774
775=item *
776
777uses dl_findfile() to determine the filename to load
778
779=item *
780
781sets @dl_require_symbols to C<("boot_$module")>
782
783=item *
784
785executes an F<auto/$module/$module.bs> file if it exists
786(typically used to add to @dl_resolve_using any files which
787are required to load the module on the current platform)
788
789=item *
790
791calls dl_load_flags() to determine how to load the file.
792
793=item *
794
795calls dl_load_file() to load the file
796
797=item *
798
799calls dl_undef_symbols() and warns if any symbols are undefined
800
801=item *
802
803calls dl_find_symbol() for "boot_$module"
804
805=item *
806
807calls dl_install_xsub() to install it as "${module}::bootstrap"
808
809=item *
810
811calls &{"${module}::bootstrap"} to bootstrap the module (actually
812it uses the function reference returned by dl_install_xsub for speed)
813
814=back
815
816=back
817
818
819=head1 AUTHOR
820
821Tim Bunce, 11 August 1994.
822
823This interface is based on the work and comments of (in no particular
824order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
825Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and others.
826
827Larry Wall designed the elegant inherited bootstrap mechanism and
828implemented the first Perl 5 dynamic loader using it.
829
830Solaris global loading added by Nick Ing-Simmons with design/coding
831assistance from Tim Bunce, January 1996.
832
833=cut
# spent 190µs within DynaLoader::CORE:ftdir which was called 6 times, avg 32µs/call: # 6 times (190µs+0s) by DynaLoader::bootstrap at line 184 of DynaLoader.pm, avg 32µs/call
sub DynaLoader::CORE:ftdir; # xsub
# spent 82µs within DynaLoader::CORE:ftfile which was called 6 times, avg 14µs/call: # 6 times (82µs+0s) by DynaLoader::bootstrap at line 188 of DynaLoader.pm, avg 14µs/call
sub DynaLoader::CORE:ftfile; # xsub
# spent 36.0ms within DynaLoader::CORE:ftsize which was called 6 times, avg 6.00ms/call: # 6 times (36.0ms+0s) by DynaLoader::bootstrap at line 209 of DynaLoader.pm, avg 6.00ms/call
sub DynaLoader::CORE:ftsize; # xsub
# spent 281µs within DynaLoader::CORE:subst which was called 12 times, avg 23µs/call: # 6 times (225µs+0s) by DynaLoader::bootstrap at line 208 of DynaLoader.pm, avg 38µs/call # 6 times (56µs+0s) by DynaLoader::bootstrap at line 201 of DynaLoader.pm, avg 9µs/call
sub DynaLoader::CORE:subst; # xsub
# spent 60µs within DynaLoader::dl_find_symbol which was called 6 times, avg 10µs/call: # 6 times (60µs+0s) by DynaLoader::bootstrap at line 241 of DynaLoader.pm, avg 10µs/call
sub DynaLoader::dl_find_symbol; # xsub
# spent 525µs within DynaLoader::dl_install_xsub which was called 6 times, avg 88µs/call: # 6 times (525µs+0s) by DynaLoader::bootstrap at line 246 of DynaLoader.pm, avg 88µs/call
sub DynaLoader::dl_install_xsub; # xsub
# spent 2.01ms within DynaLoader::dl_load_file which was called 6 times, avg 335µs/call: # 6 times (2.01ms+0s) by DynaLoader::bootstrap at line 230 of DynaLoader.pm, avg 335µs/call
sub DynaLoader::dl_load_file; # xsub
# spent 46µs within DynaLoader::dl_undef_symbols which was called 6 times, avg 8µs/call: # 6 times (46µs+0s) by DynaLoader::bootstrap at line 235 of DynaLoader.pm, avg 8µs/call
sub DynaLoader::dl_undef_symbols; # xsub
Report produced by the NYTProf 3.11 Perl profiler, developed by Tim Bunce and Adam Kaplan.