Return to prlink.h CVS log

Up to [Synchronet] / sbbs / include / mozilla / nspr

Annotation of sbbs/include/mozilla/nspr/prlink.h, revision 1.1

1.1     ! root        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___ */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.