108 lines
3.8 KiB
Markdown
108 lines
3.8 KiB
Markdown
# Dynamic Library Search
|
|
|
|
This section describes NSPR's programming interface to load, unload and
|
|
resolve symbols in dynamic libraries. It also provides a method by which
|
|
to condition symbols of statically linked code so that to other clients
|
|
it appears as though they are dynamically loaded.
|
|
|
|
(library-linking-types)=
|
|
|
|
## Library Linking Types
|
|
|
|
These data types are defined for dynamic library linking:
|
|
|
|
> - {ref}`PRLibrary`
|
|
> - {ref}`PRStaticLinkTable`
|
|
|
|
(library-linking-functions)=
|
|
|
|
## Library Linking Functions
|
|
|
|
The library linking functions are:
|
|
|
|
> - {ref}`PR_SetLibraryPath`
|
|
> - {ref}`PR_GetLibraryPath`
|
|
> - {ref}`PR_GetLibraryName`
|
|
> - {ref}`PR_FreeLibraryName`
|
|
> - {ref}`PR_LoadLibrary`
|
|
> - {ref}`PR_UnloadLibrary`
|
|
> - {ref}`PR_FindSymbol`
|
|
> - {ref}`PR_FindSymbolAndLibrary`
|
|
|
|
(finding-symbols-defined-in-the-main-executable-program)=
|
|
|
|
### Finding Symbols Defined in the Main Executable Program
|
|
|
|
{ref}`PR_LoadLibrary` cannot open a handle that references the main
|
|
executable program. (This is admittedly an omission that should be
|
|
fixed.) However, it is possible to look up symbols defined in the main
|
|
executable program as follows.
|
|
|
|
```{code}
|
|
PRLibrary *lib;
|
|
void *funcPtr;
|
|
|
|
funcPtr = PR_FindSymbolAndLibrary("FunctionName", &lib);
|
|
```
|
|
|
|
When {ref}`PR_FindSymbolAndLibrary` returns, `funcPtr` is the value of
|
|
the function pointer you want to look up, and the variable lib
|
|
references the main executable program. You can then call
|
|
{ref}`PR_FindSymbol` on lib to look up other symbols defined in the main
|
|
program. Remember to call `PR_UnloadLibrary(lib)` to close the library
|
|
handle when you are done.
|
|
|
|
(platform-notes)=
|
|
|
|
## Platform Notes
|
|
|
|
To use the dynamic library loading functions on some platforms, certain
|
|
environment variables must be set at run time, and you may need to link
|
|
your executable programs using special linker options.
|
|
|
|
This section summarizes these platform idiosyncrasies. For more
|
|
information, consult the man pages for `ld` and `dlopen` (or
|
|
`shl_load` on HP-UX) for Unix, and the `LoadLibrary` documentation
|
|
for Win32.
|
|
|
|
- [Dynamic Library Search Path](#Dynamic_Library_Search_Path)
|
|
- [Exporting Symbols from the Main Executable
|
|
Program](#Exporting_Symbols_from_the_Main_Executable_Program)
|
|
|
|
### Dynamic Library Search Path
|
|
|
|
The dynamic library search path is the list of directories in which to
|
|
look for a dynamic library. Each platform has its own standard
|
|
directories in which to look for dynamic libraries, plus a customizable
|
|
list of directories specified by an environment variable.
|
|
|
|
- On most Unix systems, this environment variable is
|
|
`LD_LIBRARY_PATH`. These systems typically use `dlopen` to load a
|
|
dynamic library.
|
|
- HP-UX uses `shl_load` to load dynamic libraries, and the
|
|
environment variable specifying the dynamic library search path is
|
|
`SHLIB_PATH`. Moreover, the executable program must be linked with
|
|
the +s option so that it will search for shared libraries in the
|
|
directories specified by `SHLIB_PATH` at run time. Alternatively,
|
|
you can enable the +s option as a postprocessing step using the
|
|
`chatr` tool. For example, link your executable program a.out
|
|
without the +s option, then execute the following:
|
|
|
|
```{code}
|
|
chatr +s enable a.out
|
|
```
|
|
|
|
- On Rhapsody, the environment variable is `DYLD_LIBRARY_PATH`.
|
|
- On Win32, the environment variable is `PATH`. The same search path
|
|
is used to search for executable programs and DLLs.
|
|
|
|
(exporting-symbols-from-the-main-executable-program)=
|
|
|
|
### Exporting Symbols from the Main Executable Program
|
|
|
|
On some systems, symbols defined in the main executable program are not
|
|
exported by default. On HP-UX, you must link the executable program with
|
|
the -E linker option in order to export all symbols in the main program
|
|
to shared libraries. If you use the GNU compilers (on any platform), you
|
|
must also link the executable program with the -E option.
|