prlink.h (8354B)
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___ */