← Index
Performance Profile   « block view • line view • sub view »
For /wise/base/deliv/dev/bin/getfix
  Run on Thu May 20 15:30:03 2010
Reported on Thu May 20 16:25:44 2010

File/opt/wise/lib/perl5/5.10.0/x86_64-linux-thread-multi/DynaLoader.pm
Statements Executed420
Total Time0.030725 seconds

Subroutines — ordered by exclusive time
Calls P F Exclusive
Time		 Inclusive
Time		 Subroutine
1010100.013540.02967DynaLoader::bootstrap
11120.009370.00937DynaLoader::dl_load_file (xsub)
11120.000150.00015DynaLoader::dl_install_xsub (xsub)
10110.000100.00010DynaLoader::dl_load_flags
11128.1e-58.1e-5DynaLoader::dl_find_symbol (xsub)
11125.0e-55.0e-5DynaLoader::dl_undef_symbols (xsub)
00000DynaLoader::BEGIN
00000DynaLoader::bootstrap_inherit
00000DynaLoader::croak

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

Report produced by the NYTProf 2.07 Perl profiler, developed by Tim Bunce and Adam Kaplan.