.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DynaLoader::Functions 3pm"
.TH DynaLoader::Functions 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DynaLoader::Functions \- deconstructed dynamic C library loading
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use DynaLoader::Functions qw(
\&        loadable_for_module
\&        linkable_for_loadable linkable_for_module);
\&
\&    $loadable = loadable_for_module("Acme::Widget");
\&    @linkable = linkable_for_loadable($loadable);
\&    @linkable = linkable_for_module("Acme::Widget");
\&
\&    use DynaLoader::Functions qw(dyna_load dyna_resolve dyna_unload);
\&
\&    $libh = dyna_load($loadable, {
\&                require_symbols => ["boot_Acme_\|_Widget"],
\&            });
\&    my $bootfunc = dyna_resolve($libh, "boot_Acme_\|_Widget");
\&    dyna_unload($libh);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a function-based interface to dynamic loading as used
by Perl.  Some details of dynamic loading are very platform-dependent,
so correct use of these functions requires the programmer to be mindful
of the space of platform variations.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "File finding"
.IX Subsection "File finding"
.IP "loadable_for_module(\s-1MODULE_NAME\s0)" 4
.IX Item "loadable_for_module(MODULE_NAME)"
\&\fI\s-1MODULE_NAME\s0\fR must be the name of a Perl module, in bareword syntax with
\&\f(CW\*(C`::\*(C'\fR separators.  The named module is presumed to be an \s-1XS\s0 extension
following standard conventions, and its runtime-loadable C library file is
searched for.  If found, the name of the library file is returned.  If it
cannot be found, the function \f(CW\*(C`die\*(C'\fRs with an informative error message.
.Sp
If the named module is actually not an \s-1XS\s0 extension, or is not installed,
or stores its C library in a non-standard place, there is a non-trivial
danger that this function will find some other library file and believe
it to be the right one.  This function should therefore only be used
when there is an expectation that the module is installed and would in
normal operation load its corresponding C library.
.IP "linkable_for_loadable(\s-1LOADABLE_FILENAME\s0)" 4
.IX Item "linkable_for_loadable(LOADABLE_FILENAME)"
If symbols in one runtime-loadable C library are to be made available
to another runtime-loadable C library, depending on the platform it
may be necessary to refer to the exporting library when linking the
importing library.  Generally this is not required on Unix, but it is
required on Windows.  Where it is required to refer to the exporting
library at link time, the file used may be the loadable library file
itself, or may be a separate file used only for this purpose.  Given the
loadable form of an exporting library, this function determines what is
required at link time for an importing library.
.Sp
\&\fI\s-1LOADABLE_FILENAME\s0\fR must be the name of a runtime-loadable C library
file.  The function checks what is required to link a library that will
at runtime import symbols from this library.  It returns a list (which
will be empty on many platforms) of names of files that must be used as
additional objects when linking the importing library.
.IP "linkable_for_module(\s-1MODULE_NAME\s0)" 4
.IX Item "linkable_for_module(MODULE_NAME)"
Performs the job of \*(L"linkable_for_loadable\*(R" (which see for explanation),
but based on a module name instead of a loadable library filename.
.Sp
\&\fI\s-1MODULE_NAME\s0\fR must be the name of a Perl module, in bareword syntax
with \f(CW\*(C`::\*(C'\fR separators.  The function checks what is required to link a
library that will at runtime import symbols from the loadable C library
associated with the module.  It returns a list (which will be empty
on many platforms) of names of files that must be used as additional
objects when linking the importing library.
.SS "Low-level dynamic loading"
.IX Subsection "Low-level dynamic loading"
.IP "dyna_load(LOADABLE_FILENAME[, \s-1OPTIONS\s0])" 4
.IX Item "dyna_load(LOADABLE_FILENAME[, OPTIONS])"
Dynamically load the runtime-loadable C library in the file named
\&\fI\s-1LOADABLE_FILENAME\s0\fR.  The process is influenced by optional information
supplied in the hash referenced by \fI\s-1OPTIONS\s0\fR.  On the platforms that
make dynamic loading easiest it is not necessary to supply any options
(in which case the parameter may be omitted), but if wide portability
is required then some options are required.  The permitted keys in the
\&\fI\s-1OPTIONS\s0\fR hash are:
.RS 4
.IP "\fBresolve_using\fR" 4
.IX Item "resolve_using"
Reference to an array, default empty, of names of additional library
files required to supply symbols used by the library being loaded.
On most platforms this is not used.  On those platforms where it is
required, the need for this will be known by whatever generated the
library to be loaded, and it will normally be set by a bootstrap file
(see \fBuse_bootstrap_options\fR below).
.IP "\fBrequire_symbols\fR" 4
.IX Item "require_symbols"
Reference to an array, default empty, of names of symbols expected to be
found in the library being loaded.  On most platforms this is not used,
but on some a library cannot be loaded without naming at least one symbol
for which a need can be satisfied by the library.
.IP "\fBuse_bootstrap_options\fR" 4
.IX Item "use_bootstrap_options"
Truth value, default false, controlling whether a \*(L"bootstrap\*(R" file will
be consulted as an additional source of options to control loading.
The \*(L"bootstrap\*(R" file, if it exists, is located in the same directory as
the loadable library file, and has a similar name differing only in its
\&\f(CW\*(C`.bs\*(C'\fR ending.
.IP "\fBsymbols_global\fR" 4
.IX Item "symbols_global"
Truth value, default false, indicating whether symbols found in the
library being loaded must be made available to subsequently-loaded
libraries.  Depending on platform, symbols may be so available even if
it is not requested.  Some platforms, on the other hand, can't provide
this facility.
.Sp
On platforms incapable of making loaded symbols globally available,
currently loading is liable to claim success while leaving the symbols
de facto unavailable.  It is intended that in the future such platforms
will instead generate an exception when this facility is requested.
.IP "\fBunresolved_action\fR" 4
.IX Item "unresolved_action"
String keyword indicating what should be done if unresolved symbols are
detected while loading the library.  It may be "\fB\s-1ERROR\s0\fR\*(L" (default)
to treat it as an error, \*(R"\fB\s-1WARN\s0\fR\*(L" to emit a warning, or \*(R"\fB\s-1IGNORE\s0\fR"
to ignore the situation.  Some platforms can't detect this problem,
so passing this check doesn't guarantee that there won't be any runtime
problems due to unresolved symbols.
.RE
.RS 4
.Sp
On success, returns a handle that can be used to refer to the loaded
library for subsequent calls to \*(L"dyna_resolve\*(R" and \*(L"dyna_unload\*(R".
On failure, \f(CW\*(C`die\*(C'\fRs.
.RE
.IP "dyna_resolve(\s-1LIBRARY_HANDLE,\s0 SYMBOL_NAME[, \s-1OPTIONS\s0])" 4
.IX Item "dyna_resolve(LIBRARY_HANDLE, SYMBOL_NAME[, OPTIONS])"
Resolve the symbol \fI\s-1SYMBOL\s0\fR in the previously-loaded library
identified by the \fI\s-1LIBRARY_HANDLE\s0\fR.  The process is influenced by
optional information supplied in the hash referenced by \fI\s-1OPTIONS\s0\fR.
The permitted keys in the \fI\s-1OPTIONS\s0\fR hash are:
.RS 4
.IP "\fBunresolved_action\fR" 4
.IX Item "unresolved_action"
String keyword indicating what should be done if the symbol cannot
be resolved.  It may be "\fB\s-1ERROR\s0\fR\*(L" (default) to treat it as an error,
\&\*(R"\fB\s-1WARN\s0\fR" to emit a warning and return \f(CW\*(C`undef\*(C'\fR, or "\fB\s-1IGNORE\s0\fR" to return
\&\f(CW\*(C`undef\*(C'\fR without a warning.
.RE
.RS 4
.Sp
On success, returns the value of the specified symbol, in a
platform-dependent format.  Returns \f(CW\*(C`undef\*(C'\fR if the symbol could not be
resolved and this is not being treated as an error.
.RE
.IP "dyna_unload(LIBRARY_HANDLE[, \s-1OPTIONS\s0])" 4
.IX Item "dyna_unload(LIBRARY_HANDLE[, OPTIONS])"
Unload the previously-loaded library identified by the \fI\s-1LIBRARY_HANDLE\s0\fR.
The process is influenced by optional information supplied in the hash
referenced by \fI\s-1OPTIONS\s0\fR.  The permitted keys in the \fI\s-1OPTIONS\s0\fR hash are:
.RS 4
.IP "\fBfail_action\fR" 4
.IX Item "fail_action"
String keyword indicating what should be done if unloading detectably
fails.  It may be "\fB\s-1ERROR\s0\fR\*(L" (default) to treat it as an error, \*(R"\fB\s-1WARN\s0\fR\*(L"
to emit a warning, or \*(R"\fB\s-1IGNORE\s0\fR" to ignore the situation.
.RE
.RS 4
.Sp
On some platforms unloading is not possible.  On any platform,
unloading can be expected to cause mayhem if any code from the library
is currently executing, if there are any live references to data in the
library, or if any symbols provided by the library are referenced by
any subsequently-loaded library.
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DynaLoader,
ExtUtils::CBuilder,
XSLoader
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2011, 2012, 2013, 2017
Andrew Main (Zefram) <zefram@fysh.org>
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.