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