DynaLoader(3perl)

💖 NAME 💖

okay bestie, so you opened DynaLoader(3perl) — that's the Perl Programmers Reference Guide version, if you were wondering — and it's literally called DynaLoader, and its whole thing is Dynamically load C libraries into Perl code. no cap, that's the job description. ✨

🚀 SYNOPSIS 🚀

package YourPackage;
require DynaLoader;
@ISA = qw(... DynaLoader ...);
__PACKAGE__->bootstrap;

# optional method for 'global' loading
sub dl_load_flags { 0x01 }

🌸 DESCRIPTION 🌸

so this page is laying out a standard generic interface to all the dynamic linking machinery that exists on a whole bunch of platforms. and its main character purpose? implementing automatic dynamic loading of Perl modules. that's the whole vibe. 👑

it's doing double duty too, bestie: it's a specification for anyone who wants to go implement DynaLoader for a brand new platform, AND a guide for anyone who wants to use DynaLoader directly in an application. two jobs, ate both. 💅

and the design goal? DynaLoader is meant to be a very simple high-level interface that's general enough to cover what SunOS, HP-UX, Linux, VMS and other platforms need. it's giving "one interface to rule the linker." 🦋

and the hope is it'll also cover the needs of OS/2, NT etc, plus allow pseudo-dynamic linking (using ld -A at runtime). manifesting that. 🙈

okay now the important part, and I need you to hear me on this: DynaLoader, by itself, is practically useless for accessing non-Perl libraries, because it provides almost no Perl-to-C 'glue'. there is, for example, no mechanism for calling a C library function or supplying arguments. that's just not what it does, bestie, don't come for it. 😭

but!! there's a C::DynaLib module available from CPAN sites that does that whole job for some common system types. and since the year 2000, there's also Inline::C, a module that lets you write Perl subroutines in C. also available from your local CPAN site. ✨

---

✨ DynaLoader Interface Summary ✨

the ~ cast list ~ of the whole module:

• @dl_library_path
• @dl_resolve_using
• @dl_require_symbols
• $dl_debug
• $dl_dlext
• @dl_librefs
• @dl_modules
• @dl_shared_objects

Implemented in: Perl 🧚

• bootstrap($modulename)
• @filepaths = dl_findfile(@names)
• $flags = $modulename->dl_load_flags
• $symref = dl_find_symbol_anywhere($symbol)

Implemented in: C 💪

• $libref = dl_load_file($filename, $flags)
• $status = dl_unload_file($libref)
• $symref = dl_find_symbol($libref, $symbol)
• @symbols = dl_undef_symbols()
• dl_install_xsub($name, $symref [, $filename])
• $message = dl_error

---

💜 @dl_library_path

the standard/default list of directories where dl_findfile() goes looking for libraries and such. directories get searched in order: $dl_library_path[0], [1], ... etc.

@dl_library_path starts out holding the list of 'normal' directories (/usr/lib, etc) that Configure figured out ($Config{'libpth'}). this is the whole portability strategy, bestie — it should keep things working across a wide range of platforms. 🌈

it should also get initialised with any other directories you can determine from the environment at runtime (such as LD_LIBRARY_PATH for SunOS).

and after initialisation, an application can absolutely mess with @dl_library_path using push and unshift before calling dl_findfile(). unshift is the move when you wanna slap directories onto the front of the search order — either to save search time or to override libraries that have the same name in the 'normal' directories. sneaky but legal. 😌

the load function that dl_load_file() calls may require an absolute pathname. that's exactly what dl_findfile() and @dl_library_path are for: searching for and returning the absolute pathname for the library/object you wish to load. 🎯

🦋 @dl_resolve_using

a list of additional libraries or other shared objects that can be used to resolve any undefined symbols that might get generated by a later call to load_file().

this is only needed on some platforms — the ones that don't handle dependent libraries automatically. for example, the Socket Perl extension library (auto/Socket/Socket.so) contains references to many socket functions which need to be resolved when it's loaded. most platforms will just automatically know where to find that 'dependent' library (e.g., /usr/lib/libsocket.so). but a few platforms need to be told the location of the dependent library explicitly. that's what @dl_resolve_using is for. 🫶

example usage:

@dl_resolve_using = dl_findfile('-lsocket');

🍓 @dl_require_symbols

a list of one or more symbol names that live in the library/object file you're about to dynamically load. once again: only required on some platforms. 🎀

⭐ @dl_librefs

an array of the handles returned by successful calls to dl_load_file(), made by bootstrap, in the order in which they were loaded. pair it with dl_find_symbol() to go looking for a symbol in any of the loaded files. 📚

🌸 @dl_modules

an array of module (package) names that have been bootstrap'ed. 🌷

🧚 @dl_shared_objects

an array of file names for the shared objects that were loaded. 💖

💅 dl_error()

syntax:

$message = dl_error();

error message text from the last failed DynaLoader function. note this, bestie, because it's giving errno in unix: a successful function call does not reset this message. 😭

implementations should detect the error as soon as it occurs in any of the other functions and save the corresponding message for later retrieval. why? because that dodges problems on some platforms (such as SunOS) where the error message is very, very temporary (e.g., dlerror()). grab it while it's hot or it's gone. 🔥

👑 $dl_debug

internal debugging messages are enabled when $dl_debug is set true. currently setting $dl_debug only affects the Perl side of the DynaLoader. these messages should help an application developer resolve any DynaLoader usage problems. (we love a helpful queen.)

$dl_debug is set to $ENV{'PERL_DL_DEBUG'} if defined.

and for the DynaLoader developer/porter there's a similar debugging variable added to the C code (see dlutils.c) and enabled if Perl was built with the -DDEBUGGING flag. this one can also be set via the PERL_DL_DEBUG environment variable. set it to 1 for minimal information, or higher for more. dial it up 🔧

🎀 $dl_dlext

when specified (localised) in a module's .pm file, this indicates the extension which the module's loadable object will have. for example:

local $DynaLoader::dl_dlext = 'unusual_ext';

that would indicate the module's loadable object has an extension of unusual_ext instead of the more usual $Config{dlext}. NOTE: this also requires that the module's Makefile.PL specify (in WriteMakefile()):

DLEXT => 'unusual_ext',

🌈 dl_findfile()

syntax:

@filepaths = dl_findfile(@names)

determines the full paths (including file suffix) of one or more loadable files given their generic names and optionally one or more directories. searches directories in @dl_library_path by default, and returns an empty list if no files were found. (sad, but honest.) 🥲

names can be specified in a variety of platform independent forms. any names in the form -lname are converted into libname.*, where .* is an appropriate suffix for the platform.

if a name doesn't already have a suitable prefix and/or suffix, then the corresponding file gets searched for by trying combinations of prefix and suffix appropriate to the platform: "$name.o", "lib$name.*" and "$name".

if any directories are included in @names, they get searched before @dl_library_path. directories may be specified as -Ldir. any other names are treated as filenames to be searched for.

using arguments of the form -Ldir and -lname is recommended. trust. ✨

example:

@dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));

🦄 dl_expandspec()

syntax:

$filepath = dl_expandspec($spec)

some unusual systems, such as VMS, require special filename handling in order to deal with symbolic names for files (i.e., VMS's Logical Names).

to support these systems, a dl_expandspec() function can be implemented either in the dl_*.xs file, or code can be added to the dl_expandspec() function in DynaLoader.pm. see DynaLoader_pm.PL for more information. 🔍

💀 dl_load_file()

syntax:

$libref = dl_load_file($filename, $flags)

dynamically loads $filename, which must be the path to a shared object or library. an opaque 'library reference' is returned as a handle for the loaded object. returns undef on error. 🙈

the $flags argument alters dl_load_file behaviour. assigned bits:

 0x01  make symbols available for linking later dl_load_file's.
       (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
       (ignored under VMS; this is a normal part of image linking)

(on systems that provide a handle for the loaded object such as SunOS and HPUX, $libref will be that handle. on other systems $libref will typically be $filename or a pointer to a buffer containing $filename. the application should not examine or alter $libref in any way. hands off, bestie. 🫳)

this is the function that does the real work. it should use the current values of @dl_require_symbols and @dl_resolve_using if required.

SunOS: dlopen($filename)
HP-UX: shl_load($filename)
Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
VMS:   lib$find_image_symbol($filename,$dl_require_symbols[0])

(the dlopen() function is also used by Solaris and some versions of Linux, and it's a common choice when providing a "wrapper" on other mechanisms, as is done in the OS/2 port.) 🌐

🧊 dl_unload_file()

syntax:

$status = dl_unload_file($libref)

dynamically unloads $libref, which must be an opaque 'library reference' as returned from dl_load_file. returns one on success and zero on failure. this function is optional and may not necessarily be provided on all platforms — so don't come for a platform that skipped it, it's allowed. 😤

if it is defined and perl is compiled with the C macro DL_UNLOAD_ALL_AT_EXIT defined, then it gets called automatically when the interpreter exits, for every shared object or library loaded by DynaLoader::bootstrap. all such library references are stored in @dl_librefs by DynaLoader::Bootstrap as it loads the libraries. and the files are unloaded in last-in, first-out order. stack behaviour, we love to see it. 📚✨

Okay so this next bit is the part where things get real — bestie, this is the unloading lore and it's giving "chaos" ngl. 💀

This unloading is usually necessary when you're embedding a shared-object perl (like, one configured with -Duseshrplib, iykyk) inside a bigger application, and the perl interpreter gets created and destroyed several times over the lifetime of that application. And in that case, the system dynamic linker can unload and then reload the shared libperl without relocating any references to it from any files that were DynaLoaded by the previous incarnation of the interpreter.

And the fallout? Any shared objects opened by DynaLoader may end up pointing to a now-invalid 'ghost' of the libperl shared object. Which means — and I cannot stress this enough — apparently random memory corruption and crashes. 💀

This behaviour is most commonly seen when using Apache and mod_perl built with the APXS mechanism. Not a vibe. Watch out. 🚨

    SunOS: dlclose($libref)
    HP-UX: ???
    Linux: ???
    VMS:   ???

(Oh and btw, the dlclose() function is also used by Solaris and some versions of Linux, and it's a common choice when providing a "wrapper" on other mechanisms — exactly like what's done in the OS/2 port.) 🫶

---

✨ dl_load_flags() ✨

Syntax:

    $flags = dl_load_flags $modulename;

So this one is designed to be a method call, and it's meant to be overridden by a derived class (aka a class that has DynaLoader chillin' in its @ISA). The definition inside DynaLoader itself just returns 0, which gives you standard behavior from dl_load_file(). Simple. Iconic. 💅

✨ dl_find_symbol() ✨

Syntax:

    $symref = dl_find_symbol($libref, $symbol)

It returns the address of the symbol $symbol, or undef if it's not found. And if your target system has separate functions for searching symbols of different types? Then dl_find_symbol() should go looking for function symbols first, and then other types. Order matters, bestie. 🌸

Now listen — the exact manner in which the address comes back inside $symref is not currently defined. The only initial requirement is that $symref can be passed to, and understood by, dl_install_xsub(). That's it. That's the whole ask. 🙈

    SunOS: dlsym($libref, $symbol)
    HP-UX: shl_findsym($libref, $symbol)
    Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
    VMS:   lib$find_image_symbol($libref,$symbol)

✨ dl_find_symbol_anywhere() ✨

Syntax:

    $symref = dl_find_symbol_anywhere($symbol)

This one's cute and easy: it just applies dl_find_symbol() to every member of @dl_librefs and hands you back the first match it finds. Periodt. 🎀

✨ dl_undef_symbols() ✨

Example:

    @symbols = dl_undef_symbols()

Returns a list of symbol names that are still undefined after load_file(). If it's not known, you get () back. And honestly? Don't even stress if your platform doesn't provide a mechanism for this. Most platforms don't need it, so they don't provide it — they just return an empty list and go about their day. 🦋

✨ dl_install_xsub() ✨

Syntax:

    dl_install_xsub($perl_name, $symref [, $filename])

Creates a brand-new Perl external subroutine named $perl_name, using $symref as the pointer to the function that implements the routine. Under the hood this is literally just a direct call to newXS()/newXS_flags(). It returns a reference to the installed function. 💅

The $filename parameter is what Perl uses to identify the source file for the function, in case die(), caller() or the debugger needs to know. And if $filename isn't defined? Then "DynaLoader" gets used instead. Easy. 😌

✨ bootstrap() ✨

Syntax:

    bootstrap($module [...])

This is the normal entry point for automatic dynamic loading in Perl, okay? Main character energy. 👑

It performs the following actions:

• locates an auto/$module directory by searching @INC
• uses dl_findfile() to determine the filename to load
• sets @dl_require_symbols to "("boot_$module")"
• executes an auto/$module/$module.bs file if it exists — typically used to add to @dl_resolve_using any files which are required to load the module on the current platform
• calls dl_load_flags() to determine how to load the file
• calls dl_load_file() to load the file
• calls dl_undef_symbols() and warns if any symbols are undefined
• calls dl_find_symbol() for "boot_$module"
• calls dl_install_xsub() to install it as "${module}::bootstrap"
• calls &{"${module}::bootstrap"} to bootstrap the module (actually it uses the function reference returned by dl_install_xsub for speed)

All arguments you pass to bootstrap() get passed along to the module's bootstrap function. The default code generated by xsubpp expects $module [, $version]. And if that optional $version argument isn't given, it defaults to "$XS_VERSION // $VERSION" in the module's symbol table. Then the default code compares the Perl-space version against the version of the compiled XS code, and croaks with an error if they don't match. Like, they gotta match, bestie. No cap. 💯

---

🌈 AUTHOR 🌈

Tim Bunce, 11 August 1994.

This interface is based on the work and comments of (in no particular order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and others. 🫶

Larry Wall designed the elegant inherited bootstrap mechanism and implemented the first Perl 5 dynamic loader using it. An icon, fr fr. 👑

Solaris global loading added by Nick Ing-Simmons, with design/coding assistance from Tim Bunce, January 1996.

---

Okay bestie, that's the whole page — and just so you know, you're reading the perl v5.44.0 version, dated 2026-10-17, and it's the DynaLoader(3perl) manual page. Now go forth and load some dynamic libraries, you gorgeous genius. Slay 💅✨🌸