dynamic_library_linking.rst (4115B)
1 Dynamic Library Search 2 ====================== 3 4 This section describes NSPR's programming interface to load, unload and 5 resolve symbols in dynamic libraries. It also provides a method by which 6 to condition symbols of statically linked code so that to other clients 7 it appears as though they are dynamically loaded. 8 9 .. _Library_Linking_Types: 10 11 Library Linking Types 12 --------------------- 13 14 These data types are defined for dynamic library linking: 15 16 - :ref:`PRLibrary` 17 - :ref:`PRStaticLinkTable` 18 19 .. _Library_Linking_Functions: 20 21 Library Linking Functions 22 ------------------------- 23 24 The library linking functions are: 25 26 - :ref:`PR_SetLibraryPath` 27 - :ref:`PR_GetLibraryPath` 28 - :ref:`PR_GetLibraryName` 29 - :ref:`PR_FreeLibraryName` 30 - :ref:`PR_LoadLibrary` 31 - :ref:`PR_UnloadLibrary` 32 - :ref:`PR_FindSymbol` 33 - :ref:`PR_FindSymbolAndLibrary` 34 35 .. _Finding_Symbols_Defined_in_the_Main_Executable_Program: 36 37 Finding Symbols Defined in the Main Executable Program 38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 39 40 :ref:`PR_LoadLibrary` cannot open a handle that references the main 41 executable program. (This is admittedly an omission that should be 42 fixed.) However, it is possible to look up symbols defined in the main 43 executable program as follows. 44 45 .. code:: 46 47 PRLibrary *lib; 48 void *funcPtr; 49 50 funcPtr = PR_FindSymbolAndLibrary("FunctionName", &lib); 51 52 When :ref:`PR_FindSymbolAndLibrary` returns, ``funcPtr`` is the value of 53 the function pointer you want to look up, and the variable lib 54 references the main executable program. You can then call 55 :ref:`PR_FindSymbol` on lib to look up other symbols defined in the main 56 program. Remember to call ``PR_UnloadLibrary(lib)`` to close the library 57 handle when you are done. 58 59 .. _Platform_Notes: 60 61 Platform Notes 62 -------------- 63 64 To use the dynamic library loading functions on some platforms, certain 65 environment variables must be set at run time, and you may need to link 66 your executable programs using special linker options. 67 68 This section summarizes these platform idiosyncrasies. For more 69 information, consult the man pages for ``ld`` and ``dlopen`` (or 70 ``shl_load`` on HP-UX) for Unix, and the ``LoadLibrary`` documentation 71 for Win32. 72 73 - `Dynamic Library Search Path <#Dynamic_Library_Search_Path>`__ 74 - `Exporting Symbols from the Main Executable 75 Program <#Exporting_Symbols_from_the_Main_Executable_Program>`__ 76 77 Dynamic Library Search Path 78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 79 80 The dynamic library search path is the list of directories in which to 81 look for a dynamic library. Each platform has its own standard 82 directories in which to look for dynamic libraries, plus a customizable 83 list of directories specified by an environment variable. 84 85 - On most Unix systems, this environment variable is 86 ``LD_LIBRARY_PATH``. These systems typically use ``dlopen`` to load a 87 dynamic library. 88 - HP-UX uses ``shl_load`` to load dynamic libraries, and the 89 environment variable specifying the dynamic library search path is 90 ``SHLIB_PATH``. Moreover, the executable program must be linked with 91 the +s option so that it will search for shared libraries in the 92 directories specified by ``SHLIB_PATH`` at run time. Alternatively, 93 you can enable the +s option as a postprocessing step using the 94 ``chatr`` tool. For example, link your executable program a.out 95 without the +s option, then execute the following: 96 97 .. code:: 98 99 chatr +s enable a.out 100 101 - On Rhapsody, the environment variable is ``DYLD_LIBRARY_PATH``. 102 - On Win32, the environment variable is ``PATH``. The same search path 103 is used to search for executable programs and DLLs. 104 105 .. _Exporting_Symbols_from_the_Main_Executable_Program: 106 107 Exporting Symbols from the Main Executable Program 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 109 110 On some systems, symbols defined in the main executable program are not 111 exported by default. On HP-UX, you must link the executable program with 112 the -E linker option in order to export all symbols in the main program 113 to shared libraries. If you use the GNU compilers (on any platform), you 114 must also link the executable program with the -E option.