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
43PR_BEGIN_EXTERN_C
44
45typedef struct PRLibrary PRLibrary;
46
47typedef 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*/
59NSPR_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*/
69NSPR_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*/
82NSPR_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*/
88NSPR_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*/
102NSPR_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
123typedef enum PRLibSpecType {
124    PR_LibSpec_Pathname,
125    PR_LibSpec_MacNamedFragment,
126    PR_LibSpec_MacIndexedFragment
127} PRLibSpecType;
128
129struct FSSpec; /* Mac OS FSSpec */
130
131typedef 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
166NSPR_API(PRLibrary *)
167PR_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*/
181NSPR_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*/
191NSPR_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*/
201typedef void (*PRFuncPtr)();
202NSPR_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*/
214NSPR_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*/
225NSPR_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*/
239NSPR_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*/
248NSPR_API(char *) PR_GetLibraryFilePathname(const char *name, PRFuncPtr addr);
249
250PR_END_EXTERN_C
251
252#endif /* prlink_h___ */
253