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___ */ 253
