Commit | Line | Data |
a0d0e21e |
1 | ======================================================================= |
2 | Specification for the Generic Dynamic Linking 'DynaLoader' Module |
3 | |
4 | This specification defines a standard generic interface to the dynamic |
5 | linking mechanisms available on many platforms. Its primary purpose is |
6 | to implement automatic dynamic loading of perl modules. |
7 | |
8 | The DynaLoader is designed to be a very simple high-level |
9 | interface that is sufficiently general to cover the requirements |
10 | of SunOS, HP-UX, NeXT, Linux, VMS and other platforms. |
11 | |
12 | It is also hoped that the interface will cover the needs of OS/2, |
13 | NT etc and allow pseudo-dynamic linking (using ld -A at runtime). |
14 | |
15 | This document serves as both a specification for anyone wishing to |
16 | implement the DynaLoader for a new platform and as a guide for |
17 | anyone wishing to use the DynaLoader directly in an application. |
18 | |
19 | It must be stressed that the DynaLoader, by itself, is practically |
20 | useless for accessing non-perl libraries because it provides almost no |
21 | perl-to-C 'glue'. There is, for example, no mechanism for calling a C |
22 | library function or supplying arguments. It is anticipated that any |
23 | glue that may be developed in the future will be implemented in a |
24 | seperate dynamically loaded module. |
25 | |
26 | This interface is based on the work and comments of (in no particular |
27 | order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno |
28 | Siegel, Thomas Neumann, Paul Marquess, Charles Bailey and others. |
29 | |
30 | Larry Wall designed the elegant inherited bootstrap mechanism and |
31 | implemented the first perl 5 dynamic loader using it. |
32 | |
33 | Tim Bunce |
34 | 11th August 1994 |
35 | |
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 | |
54 | ---------------------------------------------------------------------- |
55 | @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 |
62 | (/usr/lib etc) determined by Configure ($Config{'libpth'}). This should |
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 | |
81 | ---------------------------------------------------------------------- |
82 | @dl_resolve_using |
83 | |
84 | A list of additional libraries or other shared objects which can be |
85 | used to resolve any undefined symbols that might be generated by a |
86 | later call to load_file(). |
87 | |
88 | This is only required on some platforms which do not handle dependent |
89 | libraries automatically. For example the Socket perl extension library |
90 | (auto/Socket/Socket.so) contains references to many socket functions |
91 | which need to be resolved when it's loaded. Most platforms will |
92 | automatically know where to find the 'dependent' library (e.g., |
93 | /usr/lib/libsocket.so). A few platforms need to to be told the location |
94 | of the dependent library explicitly. Use @dl_resolve_using for this. |
95 | |
96 | Example usage: @dl_resolve_using = dl_findfile('-lsocket'); |
97 | |
98 | |
99 | ---------------------------------------------------------------------- |
100 | @dl_require_symbols |
101 | |
102 | A list of one or more symbol names that are in the library/object file |
103 | to be dynamically loaded. This is only required on some platforms. |
104 | |
105 | |
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 | |
119 | ---------------------------------------------------------------------- |
120 | $dl_debug |
121 | |
122 | Internal debugging messages are enabled when $dl_debug is set true. |
123 | Currently setting $dl_debug only affects the perl side of the |
124 | DynaLoader. These messages should help an application developer to |
125 | resolve any DynaLoader usage problems. |
126 | |
127 | $dl_debug is set to $ENV{'PERL_DL_DEBUG'} if defined. |
128 | |
129 | For the DynaLoader developer/porter there is a similar debugging |
130 | variable added to the C code (see dlutils.c) and enabled if perl is |
131 | compiled with the -DDEBUGGING flag. This can also be set via the |
132 | PERL_DL_DEBUG environment variable. Set to 1 for minimal information or |
133 | higher for more. |
134 | |
135 | |
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 '-lname' are converted into 'libname.*', where .* 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 -Ldir. Any other names |
155 | are treated as filenames to be searched for. |
156 | |
157 | Using arguments of the form -Ldir and -lname is recommended. |
158 | |
159 | Example: @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix)); |
160 | |
161 | |
162 | ---------------------------------------------------------------------- |
163 | $filepath = dl_expandspec($spec) |
164 | |
165 | Some unusual systems, such as VMS, require special filename handling in |
166 | order to deal with symbolic names for files (i.e., VMS's Logical Names). |
167 | |
168 | To support these systems a dl_expandspec function can be implemented |
169 | either in the dl_*.xs file or code can be added to the autoloadable |
170 | dl_expandspec function in DynaLoader.pm. See DynaLoader.pm for more |
171 | information. |
172 | |
173 | |
174 | |
175 | ---------------------------------------------------------------------- |
176 | $libref = dl_load_file($filename) |
177 | |
178 | Dynamically load $filename, which must be the path to a shared object |
179 | or library. An opaque 'library reference' is returned as a handle for |
180 | the loaded object. Returns undef on error. |
181 | |
182 | (On systems that provide a handle for the loaded object such as SunOS |
183 | and HPUX, $libref will be that handle. On other systems $libref will |
184 | typically be $filename or a pointer to a buffer containing $filename. |
185 | The application should not examine or alter $libref in any way.) |
186 | |
187 | This is function that does the real work. It should use the current |
188 | values of @dl_require_symbols and @dl_resolve_using if required. |
189 | |
190 | SunOS: dlopen($filename) |
191 | HP-UX: shl_load($filename) |
192 | Linux: dld_create_reference(@dl_require_symbols); dld_link($filename) |
193 | NeXT: rld_load($filename, @dl_resolve_using) |
194 | VMS: lib$find_image_symbol($filename,$dl_require_symbols[0]) |
195 | |
196 | |
197 | ---------------------------------------------------------------------- |
198 | $symref = dl_find_symbol($libref, $symbol) |
199 | |
200 | Return the address of the symbol $symbol or undef if not found. If the |
201 | target system has separate functions to search for symbols of different |
202 | types then dl_find_symbol should search for function symbols first and |
203 | then other types. |
204 | |
205 | The exact manner in which the address is returned in $symref is not |
206 | currently defined. The only initial requirement is that $symref can |
207 | be passed to, and understood by, dl_install_xsub(). |
208 | |
209 | SunOS: dlsym($libref, $symbol) |
210 | HP-UX: shl_findsym($libref, $symbol) |
211 | Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol) |
212 | NeXT: rld_lookup("_$symbol") |
213 | VMS: lib$find_image_symbol($libref,$symbol) |
214 | |
215 | |
216 | ---------------------------------------------------------------------- |
217 | @symbols = dl_undef_symbols() |
218 | |
219 | Return a list of symbol names which remain undefined after load_file(). |
220 | Returns () if not known. Don't worry if your platform does not provide |
221 | a mechanism for this. Most do not need it and hence do not provide it. |
222 | |
223 | |
224 | ---------------------------------------------------------------------- |
225 | dl_install_xsub($perl_name, $symref [, $filename]) |
226 | |
227 | Create a new Perl external subroutine named $perl_name using $symref as |
228 | a pointer to the function which implements the routine. This is simply |
229 | a direct call to newXSUB(). Returns a reference to the installed |
230 | function. |
231 | |
232 | The $filename parameter is used by Perl to identify the source file for |
233 | the function if required by die(), caller() or the debugger. If |
234 | $filename is not defined then "DynaLoader" will be used. |
235 | |
236 | |
237 | ---------------------------------------------------------------------- |
238 | bootstrap($module) |
239 | |
240 | This is the normal entry point for automatic dynamic loading in Perl. |
241 | |
242 | It performs the following actions: |
243 | 1. locates an auto/$module directory by searching @INC |
244 | 2. uses dl_findfile() to determine the filename to load |
245 | 3. sets @dl_require_symbols to ("boot_$module") |
246 | 4. executes an auto/$module/$^R/$module.bs file if it exists |
247 | (typically used to add to @dl_resolve_using any files which |
248 | are required to load the module on the current platform) |
249 | 5. calls dl_load_file() to load the file |
250 | 6. calls dl_undef_symbols() and warns if any symbols are undefined |
251 | 7. calls dl_find_symbol() for "boot_$module" |
252 | 8. calls dl_install_xsub() to install it as "${module}::bootstrap" |
253 | 9. calls &{"${module}::bootstrap"} to bootstrap the module |
254 | |
255 | |
256 | ====================================================================== |
257 | End. |