1DynaLoader::Functions(3U)ser Contributed Perl DocumentatiDoynnaLoader::Functions(3)
2
6 DynaLoader::Functions - deconstructed dynamic C library loading
7
9 use DynaLoader::Functions qw(
10 loadable_for_module
11 linkable_for_loadable linkable_for_module
12 );
13 $loadable = loadable_for_module("Acme::Widget");
15 @linkable = linkable_for_loadable($loadable);
16 @linkable = linkable_for_module("Acme::Widget");
17 use DynaLoader::Functions
19 qw(dyna_load dyna_resolve dyna_unload);
20 $libh = dyna_load($loadable, {
22 require_symbols => ["boot_Acme__Widget"],
23 });
24 my $bootfunc = dyna_resolve($libh, "boot_Acme__Widget");
25 dyna_unload($libh);
26
28 This module provides a function-based interface to dynamic loading as
29 used by Perl. Some details of dynamic loading are very platform-
30 dependent, so correct use of these functions requires the programmer to
31 be mindful of the space of platform variations.
32
34 File finding
35 loadable_for_module(MODULE_NAME)
36 MODULE_NAME must be the name of a Perl module, in bareword syntax
37 with "::" separators. The named module is presumed to be an XS
38 extension following standard conventions, and its runtime-loadable
39 C library file is searched for. If found, the name of the library
40 file is returned. If it cannot be found, the function "die"s with
41 an informative error message.
42 If the named module is actually not an XS extension, or is not
44 installed, or stores its C library in a non-standard place, there
45 is a non-trivial danger that this function will find some other
46 library file and believe it to be the right one. This function
47 should therefore only be used when there is an expectation that the
48 module is installed and would in normal operation load its
49 corresponding C library.
50 linkable_for_loadable(LOADABLE_FILENAME)
52 If symbols in one runtime-loadable C library are to be made
53 available to another runtime-loadable C library, depending on the
54 platform it may be necessary to refer to the exporting library when
55 linking the importing library. Generally this is not required on
56 Unix, but it is required on Windows. Where it is required to refer
57 to the exporting library at link time, the file used may be the
58 loadable library file itself, or may be a separate file used only
59 for this purpose. Given the loadable form of an exporting library,
60 this function determines what is required at link time for an
61 importing library.
62 LOADABLE_FILENAME must be the name of a runtime-loadable C library
64 file. The function checks what is required to link a library that
65 will at runtime import symbols from this library. It returns a
66 list (which will be empty on many platforms) of names of files that
67 must be used as additional objects when linking the importing
68 library.
69 linkable_for_module(MODULE_NAME)
71 Performs the job of "linkable_for_loadable" (which see for
72 explanation), but based on a module name instead of a loadable
73 library filename.
74 MODULE_NAME must be the name of a Perl module, in bareword syntax
76 with "::" separators. The function checks what is required to link
77 a library that will at runtime import symbols from the loadable C
78 library associated with the module. It returns a list (which will
79 be empty on many platforms) of names of files that must be used as
80 additional objects when linking the importing library.
81 Low-level dynamic loading
83 dyna_load(LOADABLE_FILENAME[, OPTIONS])
84 Dynamically load the runtime-loadable C library in the file named
85 LOADABLE_FILENAME. The process is influenced by optional
86 information supplied in the hash referenced by OPTIONS. On the
87 platforms that make dynamic loading easiest it is not necessary to
88 supply any options (in which case the parameter may be omitted),
89 but if wide portability is required then some options are required.
90 The permitted keys in the OPTIONS hash are:
91 resolve_using
93 Reference to an array, default empty, of names of additional
94 library files required to supply symbols used by the library
95 being loaded. On most platforms this is not used. On those
96 platforms where it is required, the need for this will be known
97 by whatever generated the library to be loaded, and it will
98 normally be set by a bootstrap file (see use_bootstrap_options
99 below).
100 require_symbols
102 Reference to an array, default empty, of names of symbols
103 expected to be found in the library being loaded. On most
104 platforms this is not used, but on some a library cannot be
105 loaded without naming at least one symbol for which a need can
106 be satisfied by the library.
107 use_bootstrap_options
109 Truth value, default false, controlling whether a "bootstrap"
110 file will be consulted as an additional source of options to
111 control loading. The "bootstrap" file, if it exists, is
112 located in the same directory as the loadable library file, and
113 has a similar name differing only in its ".bs" ending.
114 symbols_global
116 Truth value, default false, indicating whether symbols found in
117 the library being loaded must be made available to
118 subsequently-loaded libraries. Depending on platform, symbols
119 may be so available even if it is not requested. Some
120 platforms, on the other hand, can't provide this facility.
121 On platforms incapable of making loaded symbols globally
123 available, currently loading is liable to claim success while
124 leaving the symbols de facto unavailable. It is intended that
125 in the future such platforms will instead generate an exception
126 when this facility is requested.
127 unresolved_action
129 String keyword indicating what should be done if unresolved
130 symbols are detected while loading the library. It may be
131 "ERROR" (default) to treat it as an error, "WARN" to emit a
132 warning, or "IGNORE" to ignore the situation. Some platforms
133 can't detect this problem, so passing this check doesn't
134 guarantee that there won't be any runtime problems due to
135 unresolved symbols.
136 On success, returns a handle that can be used to refer to the
138 loaded library for subsequent calls to "dyna_resolve" and
139 "dyna_unload". On failure, "die"s.
140 dyna_resolve(LIBRARY_HANDLE, SYMBOL_NAME[, OPTIONS])
142 Resolve the symbol SYMBOL in the previously-loaded library
143 identified by the LIBRARY_HANDLE. The process is influenced by
144 optional information supplied in the hash referenced by OPTIONS.
145 The permitted keys in the OPTIONS hash are:
146 unresolved_action
148 String keyword indicating what should be done if the symbol
149 cannot be resolved. It may be "ERROR" (default) to treat it as
150 an error, "WARN" to emit a warning and return "undef", or
151 "IGNORE" to return "undef" without a warning.
152 On success, returns the value of the specified symbol, in a
154 platform-dependent format. Returns "undef" if the symbol could not
155 be resolved and this is not being treated as an error.
156 dyna_unload(LIBRARY_HANDLE[, OPTIONS])
158 Unload the previously-loaded library identified by the
159 LIBRARY_HANDLE. The process is influenced by optional information
160 supplied in the hash referenced by OPTIONS. The permitted keys in
161 the OPTIONS hash are:
162 fail_action
164 String keyword indicating what should be done if unloading
165 detectably fails. It may be "ERROR" (default) to treat it as
166 an error, "WARN" to emit a warning, or "IGNORE" to ignore the
167 situation.
168 On some platforms unloading is not possible. On any platform,
170 unloading can be expected to cause mayhem if any code from the
171 library is currently executing, if there are any live references to
172 data in the library, or if any symbols provided by the library are
173 referenced by any subsequently-loaded library.
174
176 DynaLoader, ExtUtils::CBuilder, XSLoader
177
179 Andrew Main (Zefram) <zefram@fysh.org>
180
182 Copyright (C) 2011 Andrew Main (Zefram) <zefram@fysh.org>
183
185 This module is free software; you can redistribute it and/or modify it
186 under the same terms as Perl itself.
187perl v5.12.4 2011-09-19 DynaLoader::Functions(3)