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