1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prlink.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,230 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef prlink_h___
1.10 +#define prlink_h___
1.11 +
1.12 +/*
1.13 +** API to static and dynamic linking.
1.14 +*/
1.15 +#include "prtypes.h"
1.16 +
1.17 +PR_BEGIN_EXTERN_C
1.18 +
1.19 +typedef struct PRLibrary PRLibrary;
1.20 +
1.21 +typedef struct PRStaticLinkTable {
1.22 + const char *name;
1.23 + void (*fp)(void);
1.24 +} PRStaticLinkTable;
1.25 +
1.26 +/*
1.27 +** Change the default library path to the given string. The string is
1.28 +** copied. This call will fail if it runs out of memory.
1.29 +**
1.30 +** The string provided as 'path' is copied. The caller can do whatever is
1.31 +** convenient with the argument when the function is complete.
1.32 +*/
1.33 +NSPR_API(PRStatus) PR_SetLibraryPath(const char *path);
1.34 +
1.35 +/*
1.36 +** Return a character string which contains the path used to search for
1.37 +** dynamically loadable libraries.
1.38 +**
1.39 +** The returned value is basically a copy of a PR_SetLibraryPath().
1.40 +** The storage is allocated by the runtime and becomes the responsibilty
1.41 +** of the caller.
1.42 +*/
1.43 +NSPR_API(char*) PR_GetLibraryPath(void);
1.44 +
1.45 +/*
1.46 +** Given a directory name "dir" and a library name "lib" construct a full
1.47 +** path name that will refer to the actual dynamically loaded
1.48 +** library. This does not test for existance of said file, it just
1.49 +** constructs the full filename. The name constructed is system dependent
1.50 +** and prepared for PR_LoadLibrary. The result must be free'd when the
1.51 +** caller is done with it.
1.52 +**
1.53 +** The storage for the result is allocated by the runtime and becomes the
1.54 +** responsibility of the caller.
1.55 +*/
1.56 +NSPR_API(char*) PR_GetLibraryName(const char *dir, const char *lib);
1.57 +
1.58 +/*
1.59 +**
1.60 +** Free the memory allocated, for the caller, by PR_GetLibraryName
1.61 +*/
1.62 +NSPR_API(void) PR_FreeLibraryName(char *mem);
1.63 +
1.64 +/*
1.65 +** Given a library "name" try to load the library. The argument "name"
1.66 +** is a machine-dependent name for the library, such as the full pathname
1.67 +** returned by PR_GetLibraryName. If the library is already loaded,
1.68 +** this function will avoid loading the library twice.
1.69 +**
1.70 +** If the library is loaded successfully, then a pointer to the PRLibrary
1.71 +** structure representing the library is returned. Otherwise, NULL is
1.72 +** returned.
1.73 +**
1.74 +** This increments the reference count of the library.
1.75 +*/
1.76 +NSPR_API(PRLibrary*) PR_LoadLibrary(const char *name);
1.77 +
1.78 +/*
1.79 +** Each operating system has its preferred way of specifying
1.80 +** a file in the file system. Most operating systems use
1.81 +** a pathname. Mac OS Classic, on the other hand, uses the FSSpec
1.82 +** structure to specify a file. PRLibSpec allows NSPR clients
1.83 +** to use the type of file specification that is most efficient
1.84 +** for a particular platform.
1.85 +**
1.86 +** On some operating systems such as Mac OS Classic, a shared library
1.87 +** may contain code fragments that can be individually loaded.
1.88 +** PRLibSpec also allows NSPR clients to identify a code fragment
1.89 +** in a library, if code fragments are supported by the OS.
1.90 +** A code fragment can be specified by name or by an integer index.
1.91 +**
1.92 +** Right now PRLibSpec supports four types of library specification:
1.93 +** a pathname in the native character encoding, a Mac code fragment
1.94 +** by name, a Mac code fragment by index, and a UTF-16 pathname.
1.95 +*/
1.96 +
1.97 +typedef enum PRLibSpecType {
1.98 + PR_LibSpec_Pathname,
1.99 + PR_LibSpec_MacNamedFragment, /* obsolete (for Mac OS Classic) */
1.100 + PR_LibSpec_MacIndexedFragment, /* obsolete (for Mac OS Classic) */
1.101 + PR_LibSpec_PathnameU /* supported only on Win32 */
1.102 +} PRLibSpecType;
1.103 +
1.104 +struct FSSpec; /* Mac OS Classic FSSpec */
1.105 +
1.106 +typedef struct PRLibSpec {
1.107 + PRLibSpecType type;
1.108 + union {
1.109 + /* if type is PR_LibSpec_Pathname */
1.110 + const char *pathname;
1.111 +
1.112 + /* if type is PR_LibSpec_MacNamedFragment */
1.113 + struct {
1.114 + const struct FSSpec *fsspec;
1.115 + const char *name;
1.116 + } mac_named_fragment; /* obsolete (for Mac OS Classic) */
1.117 +
1.118 + /* if type is PR_LibSpec_MacIndexedFragment */
1.119 + struct {
1.120 + const struct FSSpec *fsspec;
1.121 + PRUint32 index;
1.122 + } mac_indexed_fragment; /* obsolete (for Mac OS Classic) */
1.123 +
1.124 + /* if type is PR_LibSpec_PathnameU */
1.125 + const PRUnichar *pathname_u; /* supported only on Win32 */
1.126 + } value;
1.127 +} PRLibSpec;
1.128 +
1.129 +/*
1.130 +** The following bit flags may be or'd together and passed
1.131 +** as the 'flags' argument to PR_LoadLibraryWithFlags.
1.132 +** Flags not supported by the underlying OS are ignored.
1.133 +*/
1.134 +
1.135 +#define PR_LD_LAZY 0x1 /* equivalent to RTLD_LAZY on Unix */
1.136 +#define PR_LD_NOW 0x2 /* equivalent to RTLD_NOW on Unix */
1.137 +#define PR_LD_GLOBAL 0x4 /* equivalent to RTLD_GLOBAL on Unix */
1.138 +#define PR_LD_LOCAL 0x8 /* equivalent to RTLD_LOCAL on Unix */
1.139 +/* The following is equivalent to LOAD_WITH_ALTERED_SEARCH_PATH on Windows */
1.140 +#define PR_LD_ALT_SEARCH_PATH 0x10
1.141 +/* 0x8000 reserved for NSPR internal use */
1.142 +
1.143 +/*
1.144 +** Load the specified library, in the manner specified by 'flags'.
1.145 +*/
1.146 +
1.147 +NSPR_API(PRLibrary *)
1.148 +PR_LoadLibraryWithFlags(
1.149 + PRLibSpec libSpec, /* the shared library */
1.150 + PRIntn flags /* flags that affect the loading */
1.151 +);
1.152 +
1.153 +/*
1.154 +** Unload a previously loaded library. If the library was a static
1.155 +** library then the static link table will no longer be referenced. The
1.156 +** associated PRLibrary object is freed.
1.157 +**
1.158 +** PR_FAILURE is returned if the library cannot be unloaded.
1.159 +**
1.160 +** This function decrements the reference count of the library.
1.161 +*/
1.162 +NSPR_API(PRStatus) PR_UnloadLibrary(PRLibrary *lib);
1.163 +
1.164 +/*
1.165 +** Given the name of a procedure, return the address of the function that
1.166 +** implements the procedure, or NULL if no such function can be
1.167 +** found. This does not find symbols in the main program (the ".exe");
1.168 +** use PR_LoadStaticLibrary to register symbols in the main program.
1.169 +**
1.170 +** This function does not modify the reference count of the library.
1.171 +*/
1.172 +NSPR_API(void*) PR_FindSymbol(PRLibrary *lib, const char *name);
1.173 +
1.174 +/*
1.175 +** Similar to PR_FindSymbol, except that the return value is a pointer to
1.176 +** a function, and not a pointer to void. Casting between a data pointer
1.177 +** and a function pointer is not portable according to the C standard.
1.178 +** Any function pointer can be cast to any other function pointer.
1.179 +**
1.180 +** This function does not modify the reference count of the library.
1.181 +*/
1.182 +typedef void (*PRFuncPtr)(void);
1.183 +NSPR_API(PRFuncPtr) PR_FindFunctionSymbol(PRLibrary *lib, const char *name);
1.184 +
1.185 +/*
1.186 +** Finds a symbol in one of the currently loaded libraries. Given the
1.187 +** name of a procedure, return the address of the function that
1.188 +** implements the procedure, and return the library that contains that
1.189 +** symbol, or NULL if no such function can be found. This does not find
1.190 +** symbols in the main program (the ".exe"); use PR_AddStaticLibrary to
1.191 +** register symbols in the main program.
1.192 +**
1.193 +** This increments the reference count of the library.
1.194 +*/
1.195 +NSPR_API(void*) PR_FindSymbolAndLibrary(const char *name,
1.196 + PRLibrary* *lib);
1.197 +
1.198 +/*
1.199 +** Similar to PR_FindSymbolAndLibrary, except that the return value is
1.200 +** a pointer to a function, and not a pointer to void. Casting between a
1.201 +** data pointer and a function pointer is not portable according to the C
1.202 +** standard. Any function pointer can be cast to any other function pointer.
1.203 +**
1.204 +** This increments the reference count of the library.
1.205 +*/
1.206 +NSPR_API(PRFuncPtr) PR_FindFunctionSymbolAndLibrary(const char *name,
1.207 + PRLibrary* *lib);
1.208 +
1.209 +/*
1.210 +** Register a static link table with the runtime under the name
1.211 +** "name". The symbols present in the static link table will be made
1.212 +** available to PR_FindSymbol. If "name" is null then the symbols will be
1.213 +** made available to the library which represents the executable. The
1.214 +** tables are not copied.
1.215 +**
1.216 +** Returns the library object if successful, null otherwise.
1.217 +**
1.218 +** This increments the reference count of the library.
1.219 +*/
1.220 +NSPR_API(PRLibrary*) PR_LoadStaticLibrary(
1.221 + const char *name, const PRStaticLinkTable *table);
1.222 +
1.223 +/*
1.224 +** Return the pathname of the file that the library "name" was loaded
1.225 +** from. "addr" is the address of a function defined in the library.
1.226 +**
1.227 +** The caller is responsible for freeing the result with PR_Free.
1.228 +*/
1.229 +NSPR_API(char *) PR_GetLibraryFilePathname(const char *name, PRFuncPtr addr);
1.230 +
1.231 +PR_END_EXTERN_C
1.232 +
1.233 +#endif /* prlink_h___ */
