← Index
NYTProf Performance Profile   « block view • line view • sub view »
For 05.Domain_and_Item.t
  Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:22:23 2010

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