/crypto/heimdal/lib/kafs/README.dlfcn

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 246 lines · 190 code · 56 blank · 0 comment · 0 complexity · fe4180f5d5e3207f1aa44d5e4f5322bb MD5 · raw file

  1. Copyright (c) 1992,1993,1995,1996, Jens-Uwe Mager, Helios Software GmbH
  2. Not derived from licensed software.
  3. Permission is granted to freely use, copy, modify, and redistribute
  4. this software, provided that the author is not construed to be liable
  5. for any results of using the software, alterations are clearly marked
  6. as such, and this notice is not modified.
  7. libdl.a
  8. -------
  9. This is an emulation library to emulate the SunOS/System V.4 functions
  10. to access the runtime linker. The functions are emulated by using the
  11. AIX load() function and by reading the .loader section of the loaded
  12. module to find the exports. The to be loaded module should be linked as
  13. follows (if using AIX 3):
  14. cc -o module.so -bM:SRE -bE:module.exp -e _nostart $(OBJS)
  15. For AIX 4:
  16. cc -o module.so -bM:SRE -bE:module.exp -bnoentry $(OBJS)
  17. If you want to reference symbols from the main part of the program in a
  18. loaded module, you will have to link against the export file of the
  19. main part:
  20. cc -o main -bE:main.exp $(MAIN_OBJS)
  21. cc -o module.so -bM:SRE -bI:main.exp -bE:module.exp -bnoentry $(OBJS)
  22. Note that you explicitely have to specify what functions are supposed
  23. to be accessible from your loaded modules, this is different from
  24. SunOS/System V.4 where any global is automatically exported. If you
  25. want to export all globals, the following script might be of help:
  26. #!/bin/sh
  27. /usr/ucb/nm -g $* | awk '$2 == "B" || $2 == "D" { print $3 }'
  28. The module export file contains the symbols to be exported. Because
  29. this library uses the loader section, the final module.so file can be
  30. stripped. C++ users should build their shared objects using the script
  31. makeC++SharedLib (part of the IBM C++ compiler), this will make sure
  32. that constructors and destructors for static and global objects will be
  33. called upon loading and unloading the module. GNU C++ users should use
  34. the -shared option to g++ to link the shared object:
  35. g++ -o module.so -shared $(OBJS)
  36. If the shared object does have permissions for anybody, the shared
  37. object will be loaded into the shared library segment and it will stay
  38. there even if the main application terminates. If you rebuild your
  39. shared object after a bugfix and you want to make sure that you really
  40. get the newest version you will have to use the "slibclean" command
  41. before starting the application again to garbage collect the shared
  42. library segment. If the performance utilities (bosperf) are installed
  43. you can use the following command to see what shared objects are
  44. loaded:
  45. /usr/lpp/bosperf/genkld | sort | uniq
  46. For easier debugging you can avoid loading the shared object into the
  47. shared library segment alltogether by removing permissions for others
  48. from the module.so file:
  49. chmod o-rwx module.so
  50. This will ensure you get a fresh copy of the shared object for every
  51. dlopen() call which is loaded into the application's data segment.
  52. Usage
  53. -----
  54. void *dlopen(const char *path, int mode);
  55. This routine loads the module pointed to by path and reads its export
  56. table. If the path does not contain a '/' character, dlopen will search
  57. for the module using the LIBPATH environment variable. It returns an
  58. opaque handle to the module or NULL on error. The mode parameter can be
  59. either RTLD_LAZY (for lazy function binding) or RTLD_NOW for immediate
  60. function binding. The AIX implementation currently does treat RTLD_NOW
  61. the same as RTLD_LAZY. The flag RTLD_GLOBAL might be or'ed into the
  62. mode parameter to allow loaded modules to bind to global variables or
  63. functions in other loaded modules loaded by dlopen(). If RTLD_GLOBAL is
  64. not specified, only globals from the main part of the executable or
  65. shared libraries are used to look for undefined symbols in loaded
  66. modules.
  67. void *dlsym(void *handle, const char *symbol);
  68. This routine searches for the symbol in the module referred to by
  69. handle and returns its address. If the symbol could not be found, the
  70. function returns NULL. The return value must be casted to a proper
  71. function pointer before it can be used. SunOS/System V.4 allows handle
  72. to be a NULL pointer to refer to the module the call is made from, this
  73. is not implemented.
  74. int dlclose(void *handle);
  75. This routine unloads the module referred to by the handle and disposes
  76. of any local storage. this function returns -1 on failure. Any function
  77. pointers obtained through dlsym() should be considered invalid after
  78. closing a module.
  79. As AIX caches shared objects in the shared library segment, function
  80. pointers obtained through dlsym() might still work even though the
  81. module has been unloaded. This can introduce subtle bugs that will
  82. segment fault later if AIX garbage collects or immediatly on
  83. SunOS/System V.4 as the text segment is unmapped.
  84. char *dlerror(void);
  85. This routine can be used to retrieve a text message describing the most
  86. recent error that occured on on of the above routines. This function
  87. returns NULL if there is no error information.
  88. Initialization and termination handlers
  89. ---------------------------------------
  90. The emulation provides for an initialization and a termination
  91. handler. The dlfcn.h file contains a structure declaration named
  92. dl_info with following members:
  93. void (*init)(void);
  94. void (*fini)(void);
  95. The init function is called upon first referencing the library. The
  96. fini function is called at dlclose() time or when the process exits.
  97. The module should declare a variable named dl_info that contains this
  98. structure which must be exported. These functions correspond to the
  99. documented _init() and _fini() functions of SunOS 4.x, but these are
  100. appearently not implemented in SunOS. When using SunOS 5.0, these
  101. correspond to #pragma init and #pragma fini respectively. At the same
  102. time any static or global C++ object's constructors or destructors will
  103. be called.
  104. BUGS
  105. ----
  106. Please note that there is currently a problem with implicitely loaded
  107. shared C++ libaries: if you refer to a shared C++ library from a loaded
  108. module that is not yet used by the main program, the dlopen() emulator
  109. does not notice this and does not call the static constructors for the
  110. implicitely loaded library. This can be easily demonstrated by
  111. referencing the C++ standard streams from a loaded module if the main
  112. program is a plain C program.
  113. Jens-Uwe Mager
  114. HELIOS Software GmbH
  115. Lavesstr. 80
  116. 30159 Hannover
  117. Germany
  118. Phone: +49 511 36482-0
  119. FAX: +49 511 36482-69
  120. AppleLink: helios.de/jum
  121. Internet: jum@helios.de
  122. Revison History
  123. ---------------
  124. SCCS/s.dlfcn.h:
  125. D 1.4 95/04/25 09:36:52 jum 4 3 00018/00004/00028
  126. MRs:
  127. COMMENTS:
  128. added RTLD_GLOBAL, include and C++ guards
  129. D 1.3 92/12/27 20:58:32 jum 3 2 00001/00001/00031
  130. MRs:
  131. COMMENTS:
  132. we always have prototypes on RS/6000
  133. D 1.2 92/08/16 17:45:11 jum 2 1 00009/00000/00023
  134. MRs:
  135. COMMENTS:
  136. added dl_info structure to implement initialize and terminate functions
  137. D 1.1 92/08/02 18:08:45 jum 1 0 00023/00000/00000
  138. MRs:
  139. COMMENTS:
  140. Erstellungsdatum und -uhrzeit 92/08/02 18:08:45 von jum
  141. SCCS/s.dlfcn.c:
  142. D 1.11 96/04/10 20:12:51 jum 13 12 00037/00000/00533
  143. MRs:
  144. COMMENTS:
  145. Integrated the changes from John W. Eaton <jwe@bevo.che.wisc.edu> to initialize
  146. g++ generated shared objects.
  147. D 1.10 96/02/15 17:42:44 jum 12 10 00012/00007/00521
  148. MRs:
  149. COMMENTS:
  150. the C++ constructor and destructor chains are now called properly for either
  151. xlC 2 or xlC 3 (CSet++).
  152. D 1.9 95/09/22 11:09:38 markus 10 9 00001/00008/00527
  153. MRs:
  154. COMMENTS:
  155. Fix version number
  156. D 1.8 95/09/22 10:14:34 markus 9 8 00008/00001/00527
  157. MRs:
  158. COMMENTS:
  159. Added version number for dl lib
  160. D 1.7 95/08/14 19:08:38 jum 8 6 00026/00004/00502
  161. MRs:
  162. COMMENTS:
  163. Integrated the fixes from Kirk Benell (kirk@rsinc.com) to allow loading of
  164. shared objects generated under AIX 4. Fixed bug that symbols with exactly
  165. 8 characters would use garbage characters from the following symbol value.
  166. D 1.6 95/04/25 09:38:03 jum 6 5 00046/00006/00460
  167. MRs:
  168. COMMENTS:
  169. added handling of C++ static constructors and destructors, added RTLD_GLOBAL to bind against other loaded modules
  170. D 1.5 93/02/14 20:14:17 jum 5 4 00002/00000/00464
  171. MRs:
  172. COMMENTS:
  173. added path to dlopen error message to make clear where there error occured.
  174. D 1.4 93/01/03 19:13:56 jum 4 3 00061/00005/00403
  175. MRs:
  176. COMMENTS:
  177. to allow calling symbols in the main module call load with L_NOAUTODEFER and
  178. do a loadbind later with the main module.
  179. D 1.3 92/12/27 20:59:55 jum 3 2 00066/00008/00342
  180. MRs:
  181. COMMENTS:
  182. added search by L_GETINFO if module got loaded by LIBPATH
  183. D 1.2 92/08/16 17:45:43 jum 2 1 00074/00006/00276
  184. MRs:
  185. COMMENTS:
  186. implemented initialize and terminate functions, added reference counting to avoid multiple loads of the same library
  187. D 1.1 92/08/02 18:08:45 jum 1 0 00282/00000/00000
  188. MRs:
  189. COMMENTS:
  190. Erstellungsdatum und -uhrzeit 92/08/02 18:08:45 von jum