OLD | NEW |
| (Empty) |
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ | |
2 /* | |
3 * The contents of this file are subject to the Mozilla Public | |
4 * License Version 1.1 (the "License"); you may not use this file | |
5 * except in compliance with the License. You may obtain a copy of | |
6 * the License at http://www.mozilla.org/MPL/ | |
7 * | |
8 * Software distributed under the License is distributed on an "AS | |
9 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or | |
10 * implied. See the License for the specific language governing | |
11 * rights and limitations under the License. | |
12 * | |
13 * The Original Code is the Netscape Portable Runtime (NSPR). | |
14 * | |
15 * The Initial Developer of the Original Code is Netscape | |
16 * Communications Corporation. Portions created by Netscape are | |
17 * Copyright (C) 1998-2000 Netscape Communications Corporation. All | |
18 * Rights Reserved. | |
19 * | |
20 * Contributor(s): | |
21 * | |
22 * Alternatively, the contents of this file may be used under the | |
23 * terms of the GNU General Public License Version 2 or later (the | |
24 * "GPL"), in which case the provisions of the GPL are applicable | |
25 * instead of those above. If you wish to allow use of your | |
26 * version of this file only under the terms of the GPL and not to | |
27 * allow others to use your version of this file under the MPL, | |
28 * indicate your decision by deleting the provisions above and | |
29 * replace them with the notice and other provisions required by | |
30 * the GPL. If you do not delete the provisions above, a recipient | |
31 * may use your version of this file under either the MPL or the | |
32 * GPL. | |
33 */ | |
34 | |
35 #ifndef prlink_h___ | |
36 #define prlink_h___ | |
37 | |
38 /* | |
39 ** API to static and dynamic linking. | |
40 */ | |
41 #include "prtypes.h" | |
42 | |
43 PR_BEGIN_EXTERN_C | |
44 | |
45 typedef struct PRLibrary PRLibrary; | |
46 | |
47 typedef struct PRStaticLinkTable { | |
48 const char *name; | |
49 void (*fp)(); | |
50 } PRStaticLinkTable; | |
51 | |
52 /* | |
53 ** Change the default library path to the given string. The string is | |
54 ** copied. This call will fail if it runs out of memory. | |
55 ** | |
56 ** The string provided as 'path' is copied. The caller can do whatever is | |
57 ** convenient with the argument when the function is complete. | |
58 */ | |
59 NSPR_API(PRStatus) PR_SetLibraryPath(const char *path); | |
60 | |
61 /* | |
62 ** Return a character string which contains the path used to search for | |
63 ** dynamically loadable libraries. | |
64 ** | |
65 ** The returned value is basically a copy of a PR_SetLibraryPath(). | |
66 ** The storage is allocated by the runtime and becomes the responsibilty | |
67 ** of the caller. | |
68 */ | |
69 NSPR_API(char*) PR_GetLibraryPath(void); | |
70 | |
71 /* | |
72 ** Given a directory name "dir" and a library name "lib" construct a full | |
73 ** path name that will refer to the actual dynamically loaded | |
74 ** library. This does not test for existance of said file, it just | |
75 ** constructs the full filename. The name constructed is system dependent | |
76 ** and prepared for PR_LoadLibrary. The result must be free'd when the | |
77 ** caller is done with it. | |
78 ** | |
79 ** The storage for the result is allocated by the runtime and becomes the | |
80 ** responsibility of the caller. | |
81 */ | |
82 NSPR_API(char*) PR_GetLibraryName(const char *dir, const char *lib); | |
83 | |
84 /* | |
85 ** | |
86 ** Free the memory allocated, for the caller, by PR_GetLibraryName | |
87 */ | |
88 NSPR_API(void) PR_FreeLibraryName(char *mem); | |
89 | |
90 /* | |
91 ** Given a library "name" try to load the library. The argument "name" | |
92 ** is a machine-dependent name for the library, such as the full pathname | |
93 ** returned by PR_GetLibraryName. If the library is already loaded, | |
94 ** this function will avoid loading the library twice. | |
95 ** | |
96 ** If the library is loaded successfully, then a pointer to the PRLibrary | |
97 ** structure representing the library is returned. Otherwise, NULL is | |
98 ** returned. | |
99 ** | |
100 ** This increments the reference count of the library. | |
101 */ | |
102 NSPR_API(PRLibrary*) PR_LoadLibrary(const char *name); | |
103 | |
104 /* | |
105 ** Each operating system has its preferred way of specifying | |
106 ** a file in the file system. Most operating systems use | |
107 ** a pathname. Mac OS, on the other hand, uses the FSSpec | |
108 ** structure to specify a file. PRLibSpec allows NSPR clients | |
109 ** to use the type of file specification that is most efficient | |
110 ** for a particular platform. | |
111 ** | |
112 ** On some operating systems such as Mac OS, a shared library may | |
113 ** contain code fragments that can be individually loaded. | |
114 ** PRLibSpec also allows NSPR clients to identify a code fragment | |
115 ** in a library, if code fragments are supported by the OS. | |
116 ** A code fragment can be specified by name or by an integer index. | |
117 ** | |
118 ** Right now PRLibSpec supports three types of library specification: | |
119 ** a pathname, a Mac code fragment by name, and a Mac code fragment | |
120 ** by index. | |
121 */ | |
122 | |
123 typedef enum PRLibSpecType { | |
124 PR_LibSpec_Pathname, | |
125 PR_LibSpec_MacNamedFragment, | |
126 PR_LibSpec_MacIndexedFragment | |
127 } PRLibSpecType; | |
128 | |
129 struct FSSpec; /* Mac OS FSSpec */ | |
130 | |
131 typedef struct PRLibSpec { | |
132 PRLibSpecType type; | |
133 union { | |
134 /* if type is PR_LibSpec_Pathname */ | |
135 const char *pathname; | |
136 | |
137 /* if type is PR_LibSpec_MacNamedFragment */ | |
138 struct { | |
139 const struct FSSpec *fsspec; | |
140 const char *name; | |
141 } mac_named_fragment; | |
142 | |
143 /* if type is PR_LibSpec_MacIndexedFragment */ | |
144 struct { | |
145 const struct FSSpec *fsspec; | |
146 PRUint32 index; | |
147 } mac_indexed_fragment; | |
148 } value; | |
149 } PRLibSpec; | |
150 | |
151 /* | |
152 ** The following bit flags may be or'd together and passed | |
153 ** as the 'flags' argument to PR_LoadLibraryWithFlags. | |
154 ** Flags not supported by the underlying OS are ignored. | |
155 */ | |
156 | |
157 #define PR_LD_LAZY 0x1 /* equivalent to RTLD_LAZY on Unix */ | |
158 #define PR_LD_NOW 0x2 /* equivalent to RTLD_NOW on Unix */ | |
159 #define PR_LD_GLOBAL 0x4 /* equivalent to RTLD_GLOBAL on Unix */ | |
160 #define PR_LD_LOCAL 0x8 /* equivalent to RTLD_LOCAL on Unix */ | |
161 | |
162 /* | |
163 ** Load the specified library, in the manner specified by 'flags'. | |
164 */ | |
165 | |
166 NSPR_API(PRLibrary *) | |
167 PR_LoadLibraryWithFlags( | |
168 PRLibSpec libSpec, /* the shared library */ | |
169 PRIntn flags /* flags that affect the loading */ | |
170 ); | |
171 | |
172 /* | |
173 ** Unload a previously loaded library. If the library was a static | |
174 ** library then the static link table will no longer be referenced. The | |
175 ** associated PRLibrary object is freed. | |
176 ** | |
177 ** PR_FAILURE is returned if the library cannot be unloaded. | |
178 ** | |
179 ** This function decrements the reference count of the library. | |
180 */ | |
181 NSPR_API(PRStatus) PR_UnloadLibrary(PRLibrary *lib); | |
182 | |
183 /* | |
184 ** Given the name of a procedure, return the address of the function that | |
185 ** implements the procedure, or NULL if no such function can be | |
186 ** found. This does not find symbols in the main program (the ".exe"); | |
187 ** use PR_LoadStaticLibrary to register symbols in the main program. | |
188 ** | |
189 ** This function does not modify the reference count of the library. | |
190 */ | |
191 NSPR_API(void*) PR_FindSymbol(PRLibrary *lib, const char *name); | |
192 | |
193 /* | |
194 ** Similar to PR_FindSymbol, except that the return value is a pointer to | |
195 ** a function, and not a pointer to void. Casting between a data pointer | |
196 ** and a function pointer is not portable according to the C standard. | |
197 ** Any function pointer can be cast to any other function pointer. | |
198 ** | |
199 ** This function does not modify the reference count of the library. | |
200 */ | |
201 typedef void (*PRFuncPtr)(); | |
202 NSPR_API(PRFuncPtr) PR_FindFunctionSymbol(PRLibrary *lib, const char *name); | |
203 | |
204 /* | |
205 ** Finds a symbol in one of the currently loaded libraries. Given the | |
206 ** name of a procedure, return the address of the function that | |
207 ** implements the procedure, and return the library that contains that | |
208 ** symbol, or NULL if no such function can be found. This does not find | |
209 ** symbols in the main program (the ".exe"); use PR_AddStaticLibrary to | |
210 ** register symbols in the main program. | |
211 ** | |
212 ** This increments the reference count of the library. | |
213 */ | |
214 NSPR_API(void*) PR_FindSymbolAndLibrary(const char *name, | |
215 PRLibrary* *lib); | |
216 | |
217 /* | |
218 ** Similar to PR_FindSymbolAndLibrary, except that the return value is | |
219 ** a pointer to a function, and not a pointer to void. Casting between a | |
220 ** data pointer and a function pointer is not portable according to the C | |
221 ** standard. Any function pointer can be cast to any other function pointer. | |
222 ** | |
223 ** This increments the reference count of the library. | |
224 */ | |
225 NSPR_API(PRFuncPtr) PR_FindFunctionSymbolAndLibrary(const char *name, | |
226 PRLibrary* *lib); | |
227 | |
228 /* | |
229 ** Register a static link table with the runtime under the name | |
230 ** "name". The symbols present in the static link table will be made | |
231 ** available to PR_FindSymbol. If "name" is null then the symbols will be | |
232 ** made available to the library which represents the executable. The | |
233 ** tables are not copied. | |
234 ** | |
235 ** Returns the library object if successful, null otherwise. | |
236 ** | |
237 ** This increments the reference count of the library. | |
238 */ | |
239 NSPR_API(PRLibrary*) PR_LoadStaticLibrary( | |
240 const char *name, const PRStaticLinkTable *table); | |
241 | |
242 /* | |
243 ** Return the pathname of the file that the library "name" was loaded | |
244 ** from. "addr" is the address of a function defined in the library. | |
245 ** | |
246 ** The caller is responsible for freeing the result with PR_Free. | |
247 */ | |
248 NSPR_API(char *) PR_GetLibraryFilePathname(const char *name, PRFuncPtr addr); | |
249 | |
250 PR_END_EXTERN_C | |
251 | |
252 #endif /* prlink_h___ */ | |
OLD | NEW |