1DynaLoader::Functions(3U)ser Contributed Perl DocumentatiDoynnaLoader::Functions(3)
2
3
4

NAME

6       DynaLoader::Functions - deconstructed dynamic C library loading
7

SYNOPSIS

9           use DynaLoader::Functions qw(
10               loadable_for_module
11               linkable_for_loadable linkable_for_module);
12
13           $loadable = loadable_for_module("Acme::Widget");
14           @linkable = linkable_for_loadable($loadable);
15           @linkable = linkable_for_module("Acme::Widget");
16
17           use DynaLoader::Functions qw(dyna_load dyna_resolve dyna_unload);
18
19           $libh = dyna_load($loadable, {
20                       require_symbols => ["boot_Acme__Widget"],
21                   });
22           my $bootfunc = dyna_resolve($libh, "boot_Acme__Widget");
23           dyna_unload($libh);
24

DESCRIPTION

26       This module provides a function-based interface to dynamic loading as
27       used by Perl.  Some details of dynamic loading are very platform-
28       dependent, so correct use of these functions requires the programmer to
29       be mindful of the space of platform variations.
30

FUNCTIONS

32   File finding
33       loadable_for_module(MODULE_NAME)
34           MODULE_NAME must be the name of a Perl module, in bareword syntax
35           with "::" separators.  The named module is presumed to be an XS
36           extension following standard conventions, and its runtime-loadable
37           C library file is searched for.  If found, the name of the library
38           file is returned.  If it cannot be found, the function "die"s with
39           an informative error message.
40
41           If the named module is actually not an XS extension, or is not
42           installed, or stores its C library in a non-standard place, there
43           is a non-trivial danger that this function will find some other
44           library file and believe it to be the right one.  This function
45           should therefore only be used when there is an expectation that the
46           module is installed and would in normal operation load its
47           corresponding C library.
48
49       linkable_for_loadable(LOADABLE_FILENAME)
50           If symbols in one runtime-loadable C library are to be made
51           available to another runtime-loadable C library, depending on the
52           platform it may be necessary to refer to the exporting library when
53           linking the importing library.  Generally this is not required on
54           Unix, but it is required on Windows.  Where it is required to refer
55           to the exporting library at link time, the file used may be the
56           loadable library file itself, or may be a separate file used only
57           for this purpose.  Given the loadable form of an exporting library,
58           this function determines what is required at link time for an
59           importing library.
60
61           LOADABLE_FILENAME must be the name of a runtime-loadable C library
62           file.  The function checks what is required to link a library that
63           will at runtime import symbols from this library.  It returns a
64           list (which will be empty on many platforms) of names of files that
65           must be used as additional objects when linking the importing
66           library.
67
68       linkable_for_module(MODULE_NAME)
69           Performs the job of "linkable_for_loadable" (which see for
70           explanation), but based on a module name instead of a loadable
71           library filename.
72
73           MODULE_NAME must be the name of a Perl module, in bareword syntax
74           with "::" separators.  The function checks what is required to link
75           a library that will at runtime import symbols from the loadable C
76           library associated with the module.  It returns a list (which will
77           be empty on many platforms) of names of files that must be used as
78           additional objects when linking the importing library.
79
80   Low-level dynamic loading
81       dyna_load(LOADABLE_FILENAME[, OPTIONS])
82           Dynamically load the runtime-loadable C library in the file named
83           LOADABLE_FILENAME.  The process is influenced by optional
84           information supplied in the hash referenced by OPTIONS.  On the
85           platforms that make dynamic loading easiest it is not necessary to
86           supply any options (in which case the parameter may be omitted),
87           but if wide portability is required then some options are required.
88           The permitted keys in the OPTIONS hash are:
89
90           resolve_using
91               Reference to an array, default empty, of names of additional
92               library files required to supply symbols used by the library
93               being loaded.  On most platforms this is not used.  On those
94               platforms where it is required, the need for this will be known
95               by whatever generated the library to be loaded, and it will
96               normally be set by a bootstrap file (see use_bootstrap_options
97               below).
98
99           require_symbols
100               Reference to an array, default empty, of names of symbols
101               expected to be found in the library being loaded.  On most
102               platforms this is not used, but on some a library cannot be
103               loaded without naming at least one symbol for which a need can
104               be satisfied by the library.
105
106           use_bootstrap_options
107               Truth value, default false, controlling whether a "bootstrap"
108               file will be consulted as an additional source of options to
109               control loading.  The "bootstrap" file, if it exists, is
110               located in the same directory as the loadable library file, and
111               has a similar name differing only in its ".bs" ending.
112
113           symbols_global
114               Truth value, default false, indicating whether symbols found in
115               the library being loaded must be made available to
116               subsequently-loaded libraries.  Depending on platform, symbols
117               may be so available even if it is not requested.  Some
118               platforms, on the other hand, can't provide this facility.
119
120               On platforms incapable of making loaded symbols globally
121               available, currently loading is liable to claim success while
122               leaving the symbols de facto unavailable.  It is intended that
123               in the future such platforms will instead generate an exception
124               when this facility is requested.
125
126           unresolved_action
127               String keyword indicating what should be done if unresolved
128               symbols are detected while loading the library.  It may be
129               "ERROR" (default) to treat it as an error, "WARN" to emit a
130               warning, or "IGNORE" to ignore the situation.  Some platforms
131               can't detect this problem, so passing this check doesn't
132               guarantee that there won't be any runtime problems due to
133               unresolved symbols.
134
135           On success, returns a handle that can be used to refer to the
136           loaded library for subsequent calls to "dyna_resolve" and
137           "dyna_unload".  On failure, "die"s.
138
139       dyna_resolve(LIBRARY_HANDLE, SYMBOL_NAME[, OPTIONS])
140           Resolve the symbol SYMBOL in the previously-loaded library
141           identified by the LIBRARY_HANDLE.  The process is influenced by
142           optional information supplied in the hash referenced by OPTIONS.
143           The permitted keys in the OPTIONS hash are:
144
145           unresolved_action
146               String keyword indicating what should be done if the symbol
147               cannot be resolved.  It may be "ERROR" (default) to treat it as
148               an error, "WARN" to emit a warning and return "undef", or
149               "IGNORE" to return "undef" without a warning.
150
151           On success, returns the value of the specified symbol, in a
152           platform-dependent format.  Returns "undef" if the symbol could not
153           be resolved and this is not being treated as an error.
154
155       dyna_unload(LIBRARY_HANDLE[, OPTIONS])
156           Unload the previously-loaded library identified by the
157           LIBRARY_HANDLE.  The process is influenced by optional information
158           supplied in the hash referenced by OPTIONS.  The permitted keys in
159           the OPTIONS hash are:
160
161           fail_action
162               String keyword indicating what should be done if unloading
163               detectably fails.  It may be "ERROR" (default) to treat it as
164               an error, "WARN" to emit a warning, or "IGNORE" to ignore the
165               situation.
166
167           On some platforms unloading is not possible.  On any platform,
168           unloading can be expected to cause mayhem if any code from the
169           library is currently executing, if there are any live references to
170           data in the library, or if any symbols provided by the library are
171           referenced by any subsequently-loaded library.
172

SEE ALSO

174       DynaLoader, ExtUtils::CBuilder, XSLoader
175

AUTHOR

177       Andrew Main (Zefram) <zefram@fysh.org>
178
180       Copyright (C) 2011, 2012, 2013, 2017 Andrew Main (Zefram)
181       <zefram@fysh.org>
182

LICENSE

184       This module is free software; you can redistribute it and/or modify it
185       under the same terms as Perl itself.
186
187
188
189perl v5.32.0                      2020-07-28          DynaLoader::Functions(3)
Impressum