Debian Codegraph @

upstream/opensuse-tumbleweed/man3/DynaLoader.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "DynaLoader 3pm"
61 .TH DynaLoader 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 DynaLoader \- Dynamically load C libraries into Perl code
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 4
71 \& package YourPackage;
72 \& require DynaLoader;
73 \& @ISA = qw(... DynaLoader ...);
74 \& _\|_PACKAGE_\|_\->bootstrap;
75 \&
76 \& # optional method for \*(Aqglobal\*(Aq loading
77 \& sub dl_load_flags { 0x01 }
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 This document defines a standard generic interface to the dynamic
82 linking mechanisms available on many platforms. Its primary purpose is
83 to implement automatic dynamic loading of Perl modules.
84 .PP
85 This document serves as both a specification for anyone wishing to
86 implement the DynaLoader for a new platform and as a guide for
87 anyone wishing to use the DynaLoader directly in an application.
88 .PP
89 The DynaLoader is designed to be a very simple high\-level
90 interface that is sufficiently general to cover the requirements
91 of SunOS, HP\-UX, Linux, VMS and other platforms.
92 .PP
93 It is also hoped that the interface will cover the needs of OS/2, NT
94 etc and also allow pseudo\-dynamic linking (using \f(CW\*(C`ld \-A\*(C'\fR at runtime).
95 .PP
96 It must be stressed that the DynaLoader, by itself, is practically
97 useless for accessing non\-Perl libraries because it provides almost no
98 Perl\-to\-C \*(Aqglue\*(Aq. There is, for example, no mechanism for calling a C
99 library function or supplying arguments. A C::DynaLib module
100 is available from CPAN sites which performs that function for some
101 common system types. And since the year 2000, there\*(Aqs also Inline::C,
102 a module that allows you to write Perl subroutines in C. Also available
103 from your local CPAN site.
104 .PP
105 DynaLoader Interface Summary
106 .PP
107 .Vb 10
108 \& @dl_library_path
109 \& @dl_resolve_using
110 \& @dl_require_symbols
111 \& $dl_debug
112 \& $dl_dlext
113 \& @dl_librefs
114 \& @dl_modules
115 \& @dl_shared_objects
116 \& Implemented in:
117 \& bootstrap($modulename) Perl
118 \& @filepaths = dl_findfile(@names) Perl
119 \& $flags = $modulename\->dl_load_flags Perl
120 \& $symref = dl_find_symbol_anywhere($symbol) Perl
121 \&
122 \& $libref = dl_load_file($filename, $flags) C
123 \& $status = dl_unload_file($libref) C
124 \& $symref = dl_find_symbol($libref, $symbol) C
125 \& @symbols = dl_undef_symbols() C
126 \& dl_install_xsub($name, $symref [, $filename]) C
127 \& $message = dl_error C
128 .Ve
129 .ie n .IP @dl_library_path 4
130 .el .IP \f(CW@dl_library_path\fR 4
131 .IX Item "@dl_library_path"
132 The standard/default list of directories in which \fBdl_findfile()\fR will
133 search for libraries etc. Directories are searched in order:
134 \&\f(CW$dl_library_path\fR[0], [1], ... etc
135 .Sp
136 \&\f(CW@dl_library_path\fR is initialised to hold the list of \*(Aqnormal\*(Aq directories
137 (\fI/usr/lib\fR, etc) determined by \fBConfigure\fR (\f(CW$Config{\*(Aqlibpth\*(Aq}\fR). This should
138 ensure portability across a wide range of platforms.
139 .Sp
140 \&\f(CW@dl_library_path\fR should also be initialised with any other directories
141 that can be determined from the environment at runtime (such as
142 LD_LIBRARY_PATH for SunOS).
143 .Sp
144 After initialisation \f(CW@dl_library_path\fR can be manipulated by an
145 application using push and unshift before calling \fBdl_findfile()\fR.
146 Unshift can be used to add directories to the front of the search order
147 either to save search time or to override libraries with the same name
148 in the \*(Aqnormal\*(Aq directories.
149 .Sp
150 The load function that \fBdl_load_file()\fR calls may require an absolute
151 pathname. The \fBdl_findfile()\fR function and \f(CW@dl_library_path\fR can be
152 used to search for and return the absolute pathname for the
153 library/object that you wish to load.
154 .ie n .IP @dl_resolve_using 4
155 .el .IP \f(CW@dl_resolve_using\fR 4
156 .IX Item "@dl_resolve_using"
157 A list of additional libraries or other shared objects which can be
158 used to resolve any undefined symbols that might be generated by a
159 later call to \fBload_file()\fR.
160 .Sp
161 This is only required on some platforms which do not handle dependent
162 libraries automatically. For example the Socket Perl extension
163 library (\fIauto/Socket/Socket.so\fR) contains references to many socket
164 functions which need to be resolved when it\*(Aqs loaded. Most platforms
165 will automatically know where to find the \*(Aqdependent\*(Aq library (e.g.,
166 \&\fI/usr/lib/libsocket.so\fR). A few platforms need to be told the
167 location of the dependent library explicitly. Use \f(CW@dl_resolve_using\fR
168 for this.
169 .Sp
170 Example usage:
171 .Sp
172 .Vb 1
173 \& @dl_resolve_using = dl_findfile(\*(Aq\-lsocket\*(Aq);
174 .Ve
175 .ie n .IP @dl_require_symbols 4
176 .el .IP \f(CW@dl_require_symbols\fR 4
177 .IX Item "@dl_require_symbols"
178 A list of one or more symbol names that are in the library/object file
179 to be dynamically loaded. This is only required on some platforms.
180 .ie n .IP @dl_librefs 4
181 .el .IP \f(CW@dl_librefs\fR 4
182 .IX Item "@dl_librefs"
183 An array of the handles returned by successful calls to \fBdl_load_file()\fR,
184 made by bootstrap, in the order in which they were loaded.
185 Can be used with \fBdl_find_symbol()\fR to look for a symbol in any of
186 the loaded files.
187 .ie n .IP @dl_modules 4
188 .el .IP \f(CW@dl_modules\fR 4
189 .IX Item "@dl_modules"
190 An array of module (package) names that have been bootstrap\*(Aqed.
191 .ie n .IP @dl_shared_objects 4
192 .el .IP \f(CW@dl_shared_objects\fR 4
193 .IX Item "@dl_shared_objects"
194 An array of file names for the shared objects that were loaded.
195 .IP \fBdl_error()\fR 4
196 .IX Item "dl_error()"
197 Syntax:
198 .Sp
199 .Vb 1
200 \& $message = dl_error();
201 .Ve
202 .Sp
203 Error message text from the last failed DynaLoader function. Note
204 that, similar to errno in unix, a successful function call does not
205 reset this message.
206 .Sp
207 Implementations should detect the error as soon as it occurs in any of
208 the other functions and save the corresponding message for later
209 retrieval. This will avoid problems on some platforms (such as SunOS)
210 where the error message is very temporary (e.g., \fBdlerror()\fR).
211 .ie n .IP $dl_debug 4
212 .el .IP \f(CW$dl_debug\fR 4
213 .IX Item "$dl_debug"
214 Internal debugging messages are enabled when \f(CW$dl_debug\fR is set true.
215 Currently setting \f(CW$dl_debug\fR only affects the Perl side of the
216 DynaLoader. These messages should help an application developer to
217 resolve any DynaLoader usage problems.
218 .Sp
219 \&\f(CW$dl_debug\fR is set to \f(CW$ENV{\*(AqPERL_DL_DEBUG\*(Aq}\fR if defined.
220 .Sp
221 For the DynaLoader developer/porter there is a similar debugging
222 variable added to the C code (see dlutils.c) and enabled if Perl was
223 built with the \fB\-DDEBUGGING\fR flag. This can also be set via the
224 PERL_DL_DEBUG environment variable. Set to 1 for minimal information or
225 higher for more.
226 .ie n .IP $dl_dlext 4
227 .el .IP \f(CW$dl_dlext\fR 4
228 .IX Item "$dl_dlext"
229 When specified (localised) in a module\*(Aqs \fI.pm\fR file, indicates the extension
230 which the module\*(Aqs loadable object will have. For example:
231 .Sp
232 .Vb 1
233 \& local $DynaLoader::dl_dlext = \*(Aqunusual_ext\*(Aq;
234 .Ve
235 .Sp
236 would indicate that the module\*(Aqs loadable object has an extension of
237 \&\f(CW\*(C`unusual_ext\*(C'\fR instead of the more usual \f(CW$Config{dlext}\fR. NOTE: This also
238 requires that the module\*(Aqs \fIMakefile.PL\fR specify (in \f(CWWriteMakefile()\fR):
239 .Sp
240 .Vb 1
241 \& DLEXT => \*(Aqunusual_ext\*(Aq,
242 .Ve
243 .IP \fBdl_findfile()\fR 4
244 .IX Item "dl_findfile()"
245 Syntax:
246 .Sp
247 .Vb 1
248 \& @filepaths = dl_findfile(@names)
249 .Ve
250 .Sp
251 Determine the full paths (including file suffix) of one or more
252 loadable files given their generic names and optionally one or more
253 directories. Searches directories in \f(CW@dl_library_path\fR by default and
254 returns an empty list if no files were found.
255 .Sp
256 Names can be specified in a variety of platform independent forms. Any
257 names in the form \fB\-lname\fR are converted into \fIlibname.*\fR, where \fI.*\fR is
258 an appropriate suffix for the platform.
259 .Sp
260 If a name does not already have a suitable prefix and/or suffix then
261 the corresponding file will be searched for by trying combinations of
262 prefix and suffix appropriate to the platform: "$name.o", "lib$name.*"
263 and "$name".
264 .Sp
265 If any directories are included in \f(CW@names\fR they are searched before
266 \&\f(CW@dl_library_path\fR. Directories may be specified as \fB\-Ldir\fR. Any other
267 names are treated as filenames to be searched for.
268 .Sp
269 Using arguments of the form \f(CW\*(C`\-Ldir\*(C'\fR and \f(CW\*(C`\-lname\*(C'\fR is recommended.
270 .Sp
271 Example:
272 .Sp
273 .Vb 1
274 \& @dl_resolve_using = dl_findfile(qw(\-L/usr/5lib \-lposix));
275 .Ve
276 .IP \fBdl_expandspec()\fR 4
277 .IX Item "dl_expandspec()"
278 Syntax:
279 .Sp
280 .Vb 1
281 \& $filepath = dl_expandspec($spec)
282 .Ve
283 .Sp
284 Some unusual systems, such as VMS, require special filename handling in
285 order to deal with symbolic names for files (i.e., VMS\*(Aqs Logical Names).
286 .Sp
287 To support these systems a \fBdl_expandspec()\fR function can be implemented
288 either in the \fIdl_*.xs\fR file or code can be added to the \fBdl_expandspec()\fR
289 function in \fIDynaLoader.pm\fR. See \fIDynaLoader_pm.PL\fR for more information.
290 .IP \fBdl_load_file()\fR 4
291 .IX Item "dl_load_file()"
292 Syntax:
293 .Sp
294 .Vb 1
295 \& $libref = dl_load_file($filename, $flags)
296 .Ve
297 .Sp
298 Dynamically load \f(CW$filename\fR, which must be the path to a shared object
299 or library. An opaque \*(Aqlibrary reference\*(Aq is returned as a handle for
300 the loaded object. Returns undef on error.
301 .Sp
302 The \f(CW$flags\fR argument to alters dl_load_file behaviour.
303 Assigned bits:
304 .Sp
305 .Vb 3
306 \& 0x01 make symbols available for linking later dl_load_file\*(Aqs.
307 \& (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
308 \& (ignored under VMS; this is a normal part of image linking)
309 .Ve
310 .Sp
311 (On systems that provide a handle for the loaded object such as SunOS
312 and HPUX, \f(CW$libref\fR will be that handle. On other systems \f(CW$libref\fR will
313 typically be \f(CW$filename\fR or a pointer to a buffer containing \f(CW$filename\fR.
314 The application should not examine or alter \f(CW$libref\fR in any way.)
315 .Sp
316 This is the function that does the real work. It should use the
317 current values of \f(CW@dl_require_symbols\fR and \f(CW@dl_resolve_using\fR if required.
318 .Sp
319 .Vb 4
320 \& SunOS: dlopen($filename)
321 \& HP\-UX: shl_load($filename)
322 \& Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
323 \& VMS: lib$find_image_symbol($filename,$dl_require_symbols[0])
324 .Ve
325 .Sp
326 (The \fBdlopen()\fR function is also used by Solaris and some versions of
327 Linux, and is a common choice when providing a "wrapper" on other
328 mechanisms as is done in the OS/2 port.)
329 .IP \fBdl_unload_file()\fR 4
330 .IX Item "dl_unload_file()"
331 Syntax:
332 .Sp
333 .Vb 1
334 \& $status = dl_unload_file($libref)
335 .Ve
336 .Sp
337 Dynamically unload \f(CW$libref\fR, which must be an opaque \*(Aqlibrary reference\*(Aq as
338 returned from dl_load_file. Returns one on success and zero on failure.
339 This function is optional and may not necessarily be provided on all platforms.
340 .Sp
341 If it is defined and perl is compiled with the C macro \f(CW\*(C`DL_UNLOAD_ALL_AT_EXIT\*(C'\fR
342 defined, then it is called automatically when the interpreter exits for
343 every shared object or library loaded by DynaLoader::bootstrap. All such
344 library references are stored in \f(CW@dl_librefs\fR by DynaLoader::Bootstrap as it
345 loads the libraries. The files are unloaded in last\-in, first\-out order.
346 .Sp
347 This unloading is usually necessary when embedding a shared\-object perl (e.g.
348 one configured with \-Duseshrplib) within a larger application, and the perl
349 interpreter is created and destroyed several times within the lifetime of the
350 application. In this case it is possible that the system dynamic linker will
351 unload and then subsequently reload the shared libperl without relocating any
352 references to it from any files DynaLoaded by the previous incarnation of the
353 interpreter. As a result, any shared objects opened by DynaLoader may point to
354 a now invalid \*(Aqghost\*(Aq of the libperl shared object, causing apparently random
355 memory corruption and crashes. This behaviour is most commonly seen when using
356 Apache and mod_perl built with the APXS mechanism.
357 .Sp
358 .Vb 4
359 \& SunOS: dlclose($libref)
360 \& HP\-UX: ???
361 \& Linux: ???
362 \& VMS: ???
363 .Ve
364 .Sp
365 (The \fBdlclose()\fR function is also used by Solaris and some versions of
366 Linux, and is a common choice when providing a "wrapper" on other
367 mechanisms as is done in the OS/2 port.)
368 .IP \fBdl_load_flags()\fR 4
369 .IX Item "dl_load_flags()"
370 Syntax:
371 .Sp
372 .Vb 1
373 \& $flags = dl_load_flags $modulename;
374 .Ve
375 .Sp
376 Designed to be a method call, and to be overridden by a derived class
377 (i.e. a class which has DynaLoader in its \f(CW@ISA\fR). The definition in
378 DynaLoader itself returns 0, which produces standard behavior from
379 \&\fBdl_load_file()\fR.
380 .IP \fBdl_find_symbol()\fR 4
381 .IX Item "dl_find_symbol()"
382 Syntax:
383 .Sp
384 .Vb 1
385 \& $symref = dl_find_symbol($libref, $symbol)
386 .Ve
387 .Sp
388 Return the address of the symbol \f(CW$symbol\fR or \f(CW\*(C`undef\*(C'\fR if not found. If the
389 target system has separate functions to search for symbols of different
390 types then \fBdl_find_symbol()\fR should search for function symbols first and
391 then other types.
392 .Sp
393 The exact manner in which the address is returned in \f(CW$symref\fR is not
394 currently defined. The only initial requirement is that \f(CW$symref\fR can
395 be passed to, and understood by, \fBdl_install_xsub()\fR.
396 .Sp
397 .Vb 4
398 \& SunOS: dlsym($libref, $symbol)
399 \& HP\-UX: shl_findsym($libref, $symbol)
400 \& Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
401 \& VMS: lib$find_image_symbol($libref,$symbol)
402 .Ve
403 .IP \fBdl_find_symbol_anywhere()\fR 4
404 .IX Item "dl_find_symbol_anywhere()"
405 Syntax:
406 .Sp
407 .Vb 1
408 \& $symref = dl_find_symbol_anywhere($symbol)
409 .Ve
410 .Sp
411 Applies \fBdl_find_symbol()\fR to the members of \f(CW@dl_librefs\fR and returns
412 the first match found.
413 .IP \fBdl_undef_symbols()\fR 4
414 .IX Item "dl_undef_symbols()"
415 Example
416 .Sp
417 .Vb 1
418 \& @symbols = dl_undef_symbols()
419 .Ve
420 .Sp
421 Return a list of symbol names which remain undefined after \fBload_file()\fR.
422 Returns \f(CW\*(C`()\*(C'\fR if not known. Don\*(Aqt worry if your platform does not provide
423 a mechanism for this. Most do not need it and hence do not provide it,
424 they just return an empty list.
425 .IP \fBdl_install_xsub()\fR 4
426 .IX Item "dl_install_xsub()"
427 Syntax:
428 .Sp
429 .Vb 1
430 \& dl_install_xsub($perl_name, $symref [, $filename])
431 .Ve
432 .Sp
433 Create a new Perl external subroutine named \f(CW$perl_name\fR using \f(CW$symref\fR as
434 a pointer to the function which implements the routine. This is simply
435 a direct call to \fBnewXS()\fR/\fBnewXS_flags()\fR. Returns a reference to the installed
436 function.
437 .Sp
438 The \f(CW$filename\fR parameter is used by Perl to identify the source file for
439 the function if required by \fBdie()\fR, \fBcaller()\fR or the debugger. If
440 \&\f(CW$filename\fR is not defined then "DynaLoader" will be used.
441 .IP \fBbootstrap()\fR 4
442 .IX Item "bootstrap()"
443 Syntax:
444 .Sp
445 bootstrap($module [...])
446 .Sp
447 This is the normal entry point for automatic dynamic loading in Perl.
448 .Sp
449 It performs the following actions:
450 .RS 4
451 .IP \(bu 8
452 locates an auto/$module directory by searching \f(CW@INC\fR
453 .IP \(bu 8
454 uses \fBdl_findfile()\fR to determine the filename to load
455 .IP \(bu 8
456 sets \f(CW@dl_require_symbols\fR to \f(CW\*(C`("boot_$module")\*(C'\fR
457 .IP \(bu 8
458 executes an \fIauto/$module/$module.bs\fR file if it exists
459 (typically used to add to \f(CW@dl_resolve_using\fR any files which
460 are required to load the module on the current platform)
461 .IP \(bu 8
462 calls \fBdl_load_flags()\fR to determine how to load the file.
463 .IP \(bu 8
464 calls \fBdl_load_file()\fR to load the file
465 .IP \(bu 8
466 calls \fBdl_undef_symbols()\fR and warns if any symbols are undefined
467 .IP \(bu 8
468 calls \fBdl_find_symbol()\fR for "boot_$module"
469 .IP \(bu 8
470 calls \fBdl_install_xsub()\fR to install it as "${module}::bootstrap"
471 .IP \(bu 8
472 calls &{"${module}::bootstrap"} to bootstrap the module (actually
473 it uses the function reference returned by dl_install_xsub for speed)
474 .RE
475 .RS 4
476 .Sp
477 All arguments to \fBbootstrap()\fR are passed to the module\*(Aqs bootstrap function.
478 The default code generated by \fIxsubpp\fR expects \f(CW$module\fR [, \f(CW$version\fR]
479 If the optional \f(CW$version\fR argument is not given, it defaults to
480 \&\f(CW\*(C`$XS_VERSION // $VERSION\*(C'\fR in the module\*(Aqs symbol table. The default code
481 compares the Perl\-space version with the version of the compiled XS code,
482 and croaks with an error if they do not match.
483 .RE
484 .SH AUTHOR
485 .IX Header "AUTHOR"
486 Tim Bunce, 11 August 1994.
487 .PP
488 This interface is based on the work and comments of (in no particular
489 order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
490 Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and others.
491 .PP
492 Larry Wall designed the elegant inherited bootstrap mechanism and
493 implemented the first Perl 5 dynamic loader using it.
494 .PP
495 Solaris global loading added by Nick Ing\-Simmons with design/coding
496 assistance from Tim Bunce, January 1996.