Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | DynaLoader - Dynamically load C libraries into Perl code |
4 | |
5 | dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_find_symbol(), dl_undef_symbols(), dl_install_xsub(), boostrap() - routines used by DynaLoader modules |
6 | |
7 | =head1 SYNOPSIS |
8 | |
9 | require DynaLoader; |
10 | push (@ISA, 'DynaLoader'); |
11 | |
12 | |
13 | =head1 DESCRIPTION |
14 | |
15 | This specification defines a standard generic interface to the dynamic |
16 | linking mechanisms available on many platforms. Its primary purpose is |
17 | to implement automatic dynamic loading of Perl modules. |
18 | |
19 | The DynaLoader is designed to be a very simple high-level |
20 | interface that is sufficiently general to cover the requirements |
21 | of SunOS, HP-UX, NeXT, Linux, VMS and other platforms. |
22 | |
23 | It is also hoped that the interface will cover the needs of OS/2, |
24 | NT etc and allow pseudo-dynamic linking (using C<ld -A> at runtime). |
25 | |
26 | This document serves as both a specification for anyone wishing to |
27 | implement the DynaLoader for a new platform and as a guide for |
28 | anyone wishing to use the DynaLoader directly in an application. |
29 | |
30 | It must be stressed that the DynaLoader, by itself, is practically |
31 | useless for accessing non-Perl libraries because it provides almost no |
32 | Perl-to-C 'glue'. There is, for example, no mechanism for calling a C |
33 | library function or supplying arguments. It is anticipated that any |
34 | glue that may be developed in the future will be implemented in a |
35 | separate dynamically loaded module. |
36 | |
37 | DynaLoader Interface Summary |
38 | |
39 | @dl_library_path |
40 | @dl_resolve_using |
41 | @dl_require_symbols |
42 | $dl_debug |
43 | Implemented in: |
44 | bootstrap($modulename) Perl |
45 | @filepaths = dl_findfile(@names) Perl |
46 | |
47 | $libref = dl_load_file($filename) C |
48 | $symref = dl_find_symbol($libref, $symbol) C |
49 | @symbols = dl_undef_symbols() C |
50 | dl_install_xsub($name, $symref [, $filename]) C |
51 | $message = dl_error C |
52 | |
53 | =over 4 |
54 | |
55 | =item @dl_library_path |
56 | |
57 | The standard/default list of directories in which dl_findfile() will |
58 | search for libraries etc. Directories are searched in order: |
59 | $dl_library_path[0], [1], ... etc |
60 | |
61 | @dl_library_path is initialised to hold the list of 'normal' directories |
748a9306 |
62 | (F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}>). This should |
a0d0e21e |
63 | ensure portability across a wide range of platforms. |
64 | |
65 | @dl_library_path should also be initialised with any other directories |
66 | that can be determined from the environment at runtime (such as |
67 | LD_LIBRARY_PATH for SunOS). |
68 | |
69 | After initialisation @dl_library_path can be manipulated by an |
70 | application using push and unshift before calling dl_findfile(). |
71 | Unshift can be used to add directories to the front of the search order |
72 | either to save search time or to override libraries with the same name |
73 | in the 'normal' directories. |
74 | |
75 | The load function that dl_load_file() calls may require an absolute |
76 | pathname. The dl_findfile() function and @dl_library_path can be |
77 | used to search for and return the absolute pathname for the |
78 | library/object that you wish to load. |
79 | |
80 | =item @dl_resolve_using |
81 | |
82 | A list of additional libraries or other shared objects which can be |
83 | used to resolve any undefined symbols that might be generated by a |
84 | later call to load_file(). |
85 | |
86 | This is only required on some platforms which do not handle dependent |
87 | libraries automatically. For example the Socket Perl extension library |
88 | (F<auto/Socket/Socket.so>) contains references to many socket functions |
89 | which need to be resolved when it's loaded. Most platforms will |
90 | automatically know where to find the 'dependent' library (e.g., |
91 | F</usr/lib/libsocket.so>). A few platforms need to to be told the location |
92 | of the dependent library explicitly. Use @dl_resolve_using for this. |
93 | |
94 | Example usage: |
95 | |
96 | @dl_resolve_using = dl_findfile('-lsocket'); |
97 | |
98 | =item @dl_require_symbols |
99 | |
100 | A list of one or more symbol names that are in the library/object file |
101 | to be dynamically loaded. This is only required on some platforms. |
102 | |
103 | =item dl_error() |
104 | |
105 | Syntax: |
106 | |
107 | $message = dl_error(); |
108 | |
109 | Error message text from the last failed DynaLoader function. Note |
110 | that, similar to errno in unix, a successful function call does not |
111 | reset this message. |
112 | |
113 | Implementations should detect the error as soon as it occurs in any of |
114 | the other functions and save the corresponding message for later |
115 | retrieval. This will avoid problems on some platforms (such as SunOS) |
116 | where the error message is very temporary (e.g., dlerror()). |
117 | |
118 | =item $dl_debug |
119 | |
120 | Internal debugging messages are enabled when $dl_debug is set true. |
121 | Currently setting $dl_debug only affects the Perl side of the |
122 | DynaLoader. These messages should help an application developer to |
123 | resolve any DynaLoader usage problems. |
124 | |
125 | $dl_debug is set to C<$ENV{'PERL_DL_DEBUG'}> if defined. |
126 | |
127 | For the DynaLoader developer/porter there is a similar debugging |
128 | variable added to the C code (see dlutils.c) and enabled if Perl was |
129 | built with the B<-DDEBUGGING> flag. This can also be set via the |
130 | PERL_DL_DEBUG environment variable. Set to 1 for minimal information or |
131 | higher for more. |
132 | |
133 | =item dl_findfile() |
134 | |
135 | Syntax: |
136 | |
137 | @filepaths = dl_findfile(@names) |
138 | |
139 | Determine the full paths (including file suffix) of one or more |
140 | loadable files given their generic names and optionally one or more |
141 | directories. Searches directories in @dl_library_path by default and |
142 | returns an empty list if no files were found. |
143 | |
144 | Names can be specified in a variety of platform independent forms. Any |
145 | names in the form B<-lname> are converted into F<libname.*>, where F<.*> is |
146 | an appropriate suffix for the platform. |
147 | |
148 | If a name does not already have a suitable prefix and/or suffix then |
149 | the corresponding file will be searched for by trying combinations of |
150 | prefix and suffix appropriate to the platform: "$name.o", "lib$name.*" |
151 | and "$name". |
152 | |
153 | If any directories are included in @names they are searched before |
154 | @dl_library_path. Directories may be specified as B<-Ldir>. Any other names |
155 | are treated as filenames to be searched for. |
156 | |
157 | Using arguments of the form C<-Ldir> and C<-lname> is recommended. |
158 | |
159 | Example: |
160 | |
161 | @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix)); |
162 | |
163 | |
164 | =item dl_expandspec() |
165 | |
166 | Syntax: |
167 | |
168 | $filepath = dl_expandspec($spec) |
169 | |
170 | Some unusual systems, such as VMS, require special filename handling in |
171 | order to deal with symbolic names for files (i.e., VMS's Logical Names). |
172 | |
173 | To support these systems a dl_expandspec() function can be implemented |
174 | either in the F<dl_*.xs> file or code can be added to the autoloadable |
748a9306 |
175 | dl_expandspec(0 function in F<DynaLoader.pm>). See F<DynaLoader.pm> for more |
a0d0e21e |
176 | information. |
177 | |
178 | =item dl_load_file() |
179 | |
180 | Syntax: |
181 | |
182 | $libref = dl_load_file($filename) |
183 | |
184 | Dynamically load $filename, which must be the path to a shared object |
185 | or library. An opaque 'library reference' is returned as a handle for |
186 | the loaded object. Returns undef on error. |
187 | |
188 | (On systems that provide a handle for the loaded object such as SunOS |
189 | and HPUX, $libref will be that handle. On other systems $libref will |
190 | typically be $filename or a pointer to a buffer containing $filename. |
191 | The application should not examine or alter $libref in any way.) |
192 | |
193 | This is function that does the real work. It should use the current |
194 | values of @dl_require_symbols and @dl_resolve_using if required. |
195 | |
196 | SunOS: dlopen($filename) |
197 | HP-UX: shl_load($filename) |
198 | Linux: dld_create_reference(@dl_require_symbols); dld_link($filename) |
199 | NeXT: rld_load($filename, @dl_resolve_using) |
200 | VMS: lib$find_image_symbol($filename,$dl_require_symbols[0]) |
201 | |
202 | |
203 | =item dl_find_symbol() |
204 | |
205 | Syntax: |
206 | |
207 | $symref = dl_find_symbol($libref, $symbol) |
208 | |
209 | Return the address of the symbol $symbol or C<undef> if not found. If the |
210 | target system has separate functions to search for symbols of different |
211 | types then dl_find_symbol() should search for function symbols first and |
212 | then other types. |
213 | |
214 | The exact manner in which the address is returned in $symref is not |
215 | currently defined. The only initial requirement is that $symref can |
216 | be passed to, and understood by, dl_install_xsub(). |
217 | |
218 | SunOS: dlsym($libref, $symbol) |
219 | HP-UX: shl_findsym($libref, $symbol) |
220 | Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol) |
221 | NeXT: rld_lookup("_$symbol") |
222 | VMS: lib$find_image_symbol($libref,$symbol) |
223 | |
224 | |
225 | =item dl_undef_symbols() |
226 | |
227 | Example |
228 | |
229 | @symbols = dl_undef_symbols() |
230 | |
231 | Return a list of symbol names which remain undefined after load_file(). |
232 | Returns C<()> if not known. Don't worry if your platform does not provide |
233 | a mechanism for this. Most do not need it and hence do not provide it. |
234 | |
235 | |
236 | =item dl_install_xsub() |
237 | |
238 | Syntax: |
239 | |
240 | dl_install_xsub($perl_name, $symref [, $filename]) |
241 | |
242 | Create a new Perl external subroutine named $perl_name using $symref as |
243 | a pointer to the function which implements the routine. This is simply |
244 | a direct call to newXSUB(). Returns a reference to the installed |
245 | function. |
246 | |
247 | The $filename parameter is used by Perl to identify the source file for |
248 | the function if required by die(), caller() or the debugger. If |
249 | $filename is not defined then "DynaLoader" will be used. |
250 | |
251 | |
252 | =item boostrap() |
253 | |
254 | Syntax: |
255 | |
256 | bootstrap($module) |
257 | |
258 | This is the normal entry point for automatic dynamic loading in Perl. |
259 | |
260 | It performs the following actions: |
261 | |
262 | =over 8 |
263 | |
264 | =item * |
265 | |
266 | locates an auto/$module directory by searching @INC |
267 | |
268 | =item * |
269 | |
270 | uses dl_findfile() to determine the filename to load |
271 | |
272 | =item * |
273 | |
274 | sets @dl_require_symbols to C<("boot_$module")> |
275 | |
276 | =item * |
277 | |
278 | executes an F<auto/$module/$module.bs> file if it exists |
279 | (typically used to add to @dl_resolve_using any files which |
280 | are required to load the module on the current platform) |
281 | |
282 | =item * |
283 | |
284 | calls dl_load_file() to load the file |
285 | |
286 | =item * |
287 | |
288 | calls dl_undef_symbols() and warns if any symbols are undefined |
289 | |
290 | =item * |
291 | |
292 | calls dl_find_symbol() for "boot_$module" |
293 | |
294 | =item * |
295 | |
296 | calls dl_install_xsub() to install it as "${module}::bootstrap" |
297 | |
298 | =item * |
299 | |
300 | calls &{"${module}::bootstrap"} to bootstrap the module |
301 | |
302 | =back |
303 | |
304 | =back |
305 | |
306 | |
307 | =head1 AUTHOR |
308 | |
309 | This interface is based on the work and comments of (in no particular |
310 | order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno |
311 | Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, and others. |
312 | |
313 | Larry Wall designed the elegant inherited bootstrap mechanism and |
314 | implemented the first Perl 5 dynamic loader using it. |
315 | |
316 | Tim Bunce, 11 August 1994. |