1DynaLoader(3pm) Perl Programmers Reference Guide DynaLoader(3pm)
2
6 DynaLoader - Dynamically load C libraries into Perl code
7
9 package YourPackage;
10 require DynaLoader;
11 @ISA = qw(... DynaLoader ...);
12 bootstrap YourPackage;
13 # optional method for 'global' loading
15 sub dl_load_flags { 0x01 }
16
18 This document defines a standard generic interface to the dynamic link‐
19 ing mechanisms available on many platforms. Its primary purpose is to
20 implement automatic dynamic loading of Perl modules.
21 This document serves as both a specification for anyone wishing to
23 implement the DynaLoader for a new platform and as a guide for anyone
24 wishing to use the DynaLoader directly in an application.
25 The DynaLoader is designed to be a very simple high-level interface
27 that is sufficiently general to cover the requirements of SunOS, HP-UX,
28 NeXT, Linux, VMS and other platforms.
29 It is also hoped that the interface will cover the needs of OS/2, NT
31 etc and also allow pseudo-dynamic linking (using "ld -A" at runtime).
32 It must be stressed that the DynaLoader, by itself, is practically use‐
34 less for accessing non-Perl libraries because it provides almost no
35 Perl-to-C 'glue'. There is, for example, no mechanism for calling a C
36 library function or supplying arguments. A C::DynaLib module is avail‐
37 able from CPAN sites which performs that function for some common sys‐
38 tem types. And since the year 2000, there's also Inline::C, a module
39 that allows you to write Perl subroutines in C. Also available from
40 your local CPAN site.
41 DynaLoader Interface Summary
43 @dl_library_path
45 @dl_resolve_using
46 @dl_require_symbols
47 $dl_debug
48 @dl_librefs
49 @dl_modules
50 @dl_shared_objects
51 Implemented in:
52 bootstrap($modulename) Perl
53 @filepaths = dl_findfile(@names) Perl
54 $flags = $modulename->dl_load_flags Perl
55 $symref = dl_find_symbol_anywhere($symbol) Perl
56 $libref = dl_load_file($filename, $flags) C
58 $status = dl_unload_file($libref) C
59 $symref = dl_find_symbol($libref, $symbol) C
60 @symbols = dl_undef_symbols() C
61 dl_install_xsub($name, $symref [, $filename]) C
62 $message = dl_error C
63 @dl_library_path
65 The standard/default list of directories in which dl_findfile()
66 will search for libraries etc. Directories are searched in order:
67 $dl_library_path[0], [1], ... etc
68 @dl_library_path is initialised to hold the list of 'normal' direc‐
70 tories (/usr/lib, etc) determined by Configure ($Config{'libpth'}).
71 This should ensure portability across a wide range of platforms.
72 @dl_library_path should also be initialised with any other directo‐
74 ries that can be determined from the environment at runtime (such
75 as LD_LIBRARY_PATH for SunOS).
76 After initialisation @dl_library_path can be manipulated by an
78 application using push and unshift before calling dl_findfile().
79 Unshift can be used to add directories to the front of the search
80 order either to save search time or to override libraries with the
81 same name in the 'normal' directories.
82 The load function that dl_load_file() calls may require an absolute
84 pathname. The dl_findfile() function and @dl_library_path can be
85 used to search for and return the absolute pathname for the
86 library/object that you wish to load.
87 @dl_resolve_using
89 A list of additional libraries or other shared objects which can be
90 used to resolve any undefined symbols that might be generated by a
91 later call to load_file().
92 This is only required on some platforms which do not handle depen‐
94 dent libraries automatically. For example the Socket Perl exten‐
95 sion library (auto/Socket/Socket.so) contains references to many
96 socket functions which need to be resolved when it's loaded. Most
97 platforms will automatically know where to find the 'dependent'
98 library (e.g., /usr/lib/libsocket.so). A few platforms need to be
99 told the location of the dependent library explicitly. Use
100 @dl_resolve_using for this.
101 Example usage:
103 @dl_resolve_using = dl_findfile('-lsocket');
105 @dl_require_symbols
107 A list of one or more symbol names that are in the library/object
108 file to be dynamically loaded. This is only required on some plat‐
109 forms.
110 @dl_librefs
112 An array of the handles returned by successful calls to
113 dl_load_file(), made by bootstrap, in the order in which they were
114 loaded. Can be used with dl_find_symbol() to look for a symbol in
115 any of the loaded files.
116 @dl_modules
118 An array of module (package) names that have been bootstrap'ed.
119 @dl_shared_objects
121 An array of file names for the shared objects that were loaded.
122 dl_error()
124 Syntax:
125 $message = dl_error();
127 Error message text from the last failed DynaLoader function. Note
129 that, similar to errno in unix, a successful function call does not
130 reset this message.
131 Implementations should detect the error as soon as it occurs in any
133 of the other functions and save the corresponding message for later
134 retrieval. This will avoid problems on some platforms (such as
135 SunOS) where the error message is very temporary (e.g., dlerror()).
136 $dl_debug
138 Internal debugging messages are enabled when $dl_debug is set true.
139 Currently setting $dl_debug only affects the Perl side of the
140 DynaLoader. These messages should help an application developer to
141 resolve any DynaLoader usage problems.
142 $dl_debug is set to $ENV{'PERL_DL_DEBUG'} if defined.
144 For the DynaLoader developer/porter there is a similar debugging
146 variable added to the C code (see dlutils.c) and enabled if Perl
147 was built with the -DDEBUGGING flag. This can also be set via the
148 PERL_DL_DEBUG environment variable. Set to 1 for minimal informa‐
149 tion or higher for more.
150 dl_findfile()
152 Syntax:
153 @filepaths = dl_findfile(@names)
155 Determine the full paths (including file suffix) of one or more
157 loadable files given their generic names and optionally one or more
158 directories. Searches directories in @dl_library_path by default
159 and returns an empty list if no files were found.
160 Names can be specified in a variety of platform independent forms.
162 Any names in the form -lname are converted into libname.*, where .*
163 is an appropriate suffix for the platform.
164 If a name does not already have a suitable prefix and/or suffix
166 then the corresponding file will be searched for by trying combina‐
167 tions of prefix and suffix appropriate to the platform: "$name.o",
168 "lib$name.*" and "$name".
169 If any directories are included in @names they are searched before
171 @dl_library_path. Directories may be specified as -Ldir. Any
172 other names are treated as filenames to be searched for.
173 Using arguments of the form "-Ldir" and "-lname" is recommended.
175 Example:
177 @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));
179 dl_expandspec()
181 Syntax:
182 $filepath = dl_expandspec($spec)
184 Some unusual systems, such as VMS, require special filename han‐
186 dling in order to deal with symbolic names for files (i.e., VMS's
187 Logical Names).
188 To support these systems a dl_expandspec() function can be imple‐
190 mented either in the dl_*.xs file or code can be added to the
191 autoloadable dl_expandspec() function in DynaLoader.pm. See
192 DynaLoader.pm for more information.
193 dl_load_file()
195 Syntax:
196 $libref = dl_load_file($filename, $flags)
198 Dynamically load $filename, which must be the path to a shared
200 object or library. An opaque 'library reference' is returned as a
201 handle for the loaded object. Returns undef on error.
202 The $flags argument to alters dl_load_file behaviour. Assigned
204 bits:
205 0x01 make symbols available for linking later dl_load_file's.
207 (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
208 (ignored under VMS; this is a normal part of image linking)
209 (On systems that provide a handle for the loaded object such as
211 SunOS and HPUX, $libref will be that handle. On other systems
212 $libref will typically be $filename or a pointer to a buffer con‐
213 taining $filename. The application should not examine or alter
214 $libref in any way.)
215 This is the function that does the real work. It should use the
217 current values of @dl_require_symbols and @dl_resolve_using if
218 required.
219 SunOS: dlopen($filename)
221 HP-UX: shl_load($filename)
222 Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
223 NeXT: rld_load($filename, @dl_resolve_using)
224 VMS: lib$find_image_symbol($filename,$dl_require_symbols[0])
225 (The dlopen() function is also used by Solaris and some versions of
227 Linux, and is a common choice when providing a "wrapper" on other
228 mechanisms as is done in the OS/2 port.)
229 dl_unload_file()
231 Syntax:
232 $status = dl_unload_file($libref)
234 Dynamically unload $libref, which must be an opaque 'library refer‐
236 ence' as returned from dl_load_file. Returns one on success and
237 zero on failure.
238 This function is optional and may not necessarily be provided on
240 all platforms. If it is defined, it is called automatically when
241 the interpreter exits for every shared object or library loaded by
242 DynaLoader::bootstrap. All such library references are stored in
243 @dl_librefs by DynaLoader::Bootstrap as it loads the libraries.
244 The files are unloaded in last-in, first-out order.
245 This unloading is usually necessary when embedding a shared-object
247 perl (e.g. one configured with -Duseshrplib) within a larger
248 application, and the perl interpreter is created and destroyed sev‐
249 eral times within the lifetime of the application. In this case it
250 is possible that the system dynamic linker will unload and then
251 subsequently reload the shared libperl without relocating any ref‐
252 erences to it from any files DynaLoaded by the previous incarnation
253 of the interpreter. As a result, any shared objects opened by
254 DynaLoader may point to a now invalid 'ghost' of the libperl shared
255 object, causing apparently random memory corruption and crashes.
256 This behaviour is most commonly seen when using Apache and mod_perl
257 built with the APXS mechanism.
258 SunOS: dlclose($libref)
260 HP-UX: ???
261 Linux: ???
262 NeXT: ???
263 VMS: ???
264 (The dlclose() function is also used by Solaris and some versions
266 of Linux, and is a common choice when providing a "wrapper" on
267 other mechanisms as is done in the OS/2 port.)
268 dl_load_flags()
270 Syntax:
271 $flags = dl_load_flags $modulename;
273 Designed to be a method call, and to be overridden by a derived
275 class (i.e. a class which has DynaLoader in its @ISA). The defini‐
276 tion in DynaLoader itself returns 0, which produces standard behav‐
277 ior from dl_load_file().
278 dl_find_symbol()
280 Syntax:
281 $symref = dl_find_symbol($libref, $symbol)
283 Return the address of the symbol $symbol or "undef" if not found.
285 If the target system has separate functions to search for symbols
286 of different types then dl_find_symbol() should search for function
287 symbols first and then other types.
288 The exact manner in which the address is returned in $symref is not
290 currently defined. The only initial requirement is that $symref
291 can be passed to, and understood by, dl_install_xsub().
292 SunOS: dlsym($libref, $symbol)
294 HP-UX: shl_findsym($libref, $symbol)
295 Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
296 NeXT: rld_lookup("_$symbol")
297 VMS: lib$find_image_symbol($libref,$symbol)
298 dl_find_symbol_anywhere()
300 Syntax:
301 $symref = dl_find_symbol_anywhere($symbol)
303 Applies dl_find_symbol() to the members of @dl_librefs and returns
305 the first match found.
306 dl_undef_symbols()
308 Example
309 @symbols = dl_undef_symbols()
311 Return a list of symbol names which remain undefined after
313 load_file(). Returns "()" if not known. Don't worry if your plat‐
314 form does not provide a mechanism for this. Most do not need it
315 and hence do not provide it, they just return an empty list.
316 dl_install_xsub()
318 Syntax:
319 dl_install_xsub($perl_name, $symref [, $filename])
321 Create a new Perl external subroutine named $perl_name using $sym‐
323 ref as a pointer to the function which implements the routine.
324 This is simply a direct call to newXSUB(). Returns a reference to
325 the installed function.
326 The $filename parameter is used by Perl to identify the source file
328 for the function if required by die(), caller() or the debugger.
329 If $filename is not defined then "DynaLoader" will be used.
330 bootstrap()
332 Syntax:
333 bootstrap($module)
335 This is the normal entry point for automatic dynamic loading in
337 Perl.
338 It performs the following actions:
340 * locates an auto/$module directory by searching @INC
342 * uses dl_findfile() to determine the filename to load
344 * sets @dl_require_symbols to "("boot_$module")"
346 * executes an auto/$module/$module.bs file if it exists (typ‐
348 ically used to add to @dl_resolve_using any files which are
349 required to load the module on the current platform)
350 * calls dl_load_flags() to determine how to load the file.
352 * calls dl_load_file() to load the file
354 * calls dl_undef_symbols() and warns if any symbols are unde‐
356 fined
357 * calls dl_find_symbol() for "boot_$module"
359 * calls dl_install_xsub() to install it as "${module}::boot‐
361 strap"
362 * calls &{"${module}::bootstrap"} to bootstrap the module
364 (actually it uses the function reference returned by
365 dl_install_xsub for speed)
366
368 Tim Bunce, 11 August 1994.
369 This interface is based on the work and comments of (in no particular
371 order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
372 Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and oth‐
373 ers.
374 Larry Wall designed the elegant inherited bootstrap mechanism and
376 implemented the first Perl 5 dynamic loader using it.
377 Solaris global loading added by Nick Ing-Simmons with design/coding
379 assistance from Tim Bunce, January 1996.
380perl v5.8.8 2001-09-21 DynaLoader(3pm)