crypto/kerberosIV/lib/kafs/README.dlfcn

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