From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- docs/nspr/reference/dynamic_library_linking.rst | 114 ++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 docs/nspr/reference/dynamic_library_linking.rst (limited to 'docs/nspr/reference/dynamic_library_linking.rst') diff --git a/docs/nspr/reference/dynamic_library_linking.rst b/docs/nspr/reference/dynamic_library_linking.rst new file mode 100644 index 0000000000..6ab8d33840 --- /dev/null +++ b/docs/nspr/reference/dynamic_library_linking.rst @@ -0,0 +1,114 @@ +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. -- cgit v1.2.3