third_party/npapi/npspy/extern/nspr/prlink.h

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