src/backend/port/dynloader/README.dlfcn.aix

   1 $PostgreSQL$
   2
   3 dynaloader
   4 ==========
   5
   6 Copyright (c) 1992,1993,1995, Jens-Uwe Mager, Helios Software GmbH
   7 Not derived from licensed software.
   8
   9 Permission is granted to freely use, copy, modify, and redistribute
  10 this software, provided that no attempt is made to gain profit from it,
  11 the author is not construed to be liable for any results of using the
  12 software, alterations are clearly marked as such, and this notice is
  13 not modified.
  14
  15 libdl.a
  16 -------
  17
  18 This is an emulation library to emulate the SunOS/System V.4 functions
  19 to access the runtime linker. The functions are emulated by using the
  20 AIX load() function and by reading the .loader section of the loaded
  21 module to find the exports. The to be loaded module should be linked as
  22 follows (if using AIX 3):
  23
  24         cc -o module.so -bM:SRE -bE:module.exp -e _nostart $(OBJS)
  25
  26 For AIX 4:
  27
  28         cc -o module.so -bM:SRE -bE:module.exp -bnoentry $(OBJS)
  29
  30 The module export file contains the symbols to be exported. Because
  31 this library uses the loader section, the final module.so file can be
  32 stripped. C++ users should build their shared objects using the script
  33 makeC++SharedLib (part of the IBM C++ compiler), this will make sure
  34 that constructors and destructors for static and global objects will be
  35 called upon loading and unloading the module.
  36
  37 Usage
  38 -----
  39
  40 void *dlopen(const char *path, int mode);
  41
  42 This routine loads the module pointed to by path and reads its export
  43 table. If the path does not contain a '/' character, dlopen will search
  44 for the module using the LIBPATH environment variable. It returns an
  45 opaque handle to the module or NULL on error. The mode parameter can be
  46 either RTLD_LAZY (for lazy function binding) or RTLD_NOW for immediate
  47 function binding. The AIX implementation currently behaves as RTLD_NOW
  48 even if RTLD_LAZY is specified. The flag RTLD_GLOBAL might be or'ed into the
  49 mode parameter to allow loaded modules to bind to global variables or
  50 functions in other loaded modules loaded by dlopen(). If RTLD_GLOBAL is
  51 not specified, only globals from the main part of the executable or
  52 shared libraries are used to look for undefined symbols in loaded
  53 modules.
  54
  55
  56 void *dlsym(void *handle, const char *symbol);
  57
  58 This routine searches for the symbol in the module referred to by
  59 handle and returns its address. If the symbol could not be found, the
  60 function returns NULL. The return value must be casted to a proper
  61 function pointer before it can be used. SunOS/System V.4 allow handle
  62 to be a NULL pointer to refer to the module the call is made from, this
  63 is not implemented.
  64
  65 int dlclose(void *handle);
  66
  67 This routine unloads the module referred to by the handle and disposes
  68 of any local storage. this function returns -1 on failure.
  69
  70 char *dlerror(void);
  71
  72 This routine can be used to retrieve a text message describing the most
  73 recent error that occured on on of the above routines. This function
  74 returns NULL if there is not error information.
  75
  76 Initialization and termination handlers
  77 ---------------------------------------
  78
  79 The emulation provides for an initialization and a termination
  80 handler.  The dlfcn.h file contains a structure declaration named
  81 dl_info with following members:
  82
  83         void (*init)(void);
  84         void (*fini)(void);
  85
  86 The init function is called upon first referencing the library. The
  87 fini function is called at dlclose() time or when the process exits.
  88 The module should declare a variable named dl_info that contains this
  89 structure which must be exported.  These functions correspond to the
  90 documented _init() and _fini() functions of SunOS 4.x, but these are
  91 appearently not implemented in SunOS.  When using SunOS 5.0, these
  92 correspond to #pragma init and #pragma fini respectively. At the same
  93 time any static or global C++ object's constructors or destructors will
  94 be called.
  95
  96 Jens-Uwe Mager
  97
  98 HELIOS Software GmbH
  99 Lavesstr. 80
 100 30159 Hannover
 101 Germany
 102
 103 Phone:          +49 511 36482-0
 104 FAX:            +49 511 36482-69
 105 AppleLink:      helios.de       Attn: Jens-Uwe Mager
 106 Internet:       jum@helios.de
 107
 108 Revison History
 109 ---------------
 110
 111 SCCS/s.dlfcn.h:
 112
 113 D 1.4 95/04/25 09:36:52 jum 4 3 00018/00004/00028
 114 MRs:
 115 COMMENTS:
 116 added RTLD_GLOBAL, include and C++ guards
 117
 118 D 1.3 92/12/27 20:58:32 jum 3 2 00001/00001/00031
 119 MRs:
 120 COMMENTS:
 121 we always have prototypes on RS/6000
 122
 123 D 1.2 92/08/16 17:45:11 jum 2 1 00009/00000/00023
 124 MRs:
 125 COMMENTS:
 126 added dl_info structure to implement initialize and terminate functions
 127
 128 D 1.1 92/08/02 18:08:45 jum 1 0 00023/00000/00000
 129 MRs:
 130 COMMENTS:
 131 Erstellungsdatum und -uhrzeit 92/08/02 18:08:45 von jum
 132
 133 SCCS/s.dlfcn.c:
 134
 135 D 1.7 95/08/14 19:08:38 jum 8 6 00026/00004/00502
 136 MRs:
 137 COMMENTS:
 138 Integrated the fixes from Kirk Benell (kirk@rsinc.com) to allow loading of
 139 shared objects generated under AIX 4. Fixed bug that symbols with exactly
 140 8 characters would use garbage characters from the following symbol value.
 141
 142 D 1.6 95/04/25 09:38:03 jum 6 5 00046/00006/00460
 143 MRs:
 144 COMMENTS:
 145 added handling of C++ static constructors and destructors, added RTLD_GLOBAL to bind against other loaded modules
 146
 147 D 1.5 93/02/14 20:14:17 jum 5 4 00002/00000/00464
 148 MRs:
 149 COMMENTS:
 150 added path to dlopen error message to make clear where there error occured.
 151
 152 D 1.4 93/01/03 19:13:56 jum 4 3 00061/00005/00403
 153 MRs:
 154 COMMENTS:
 155 to allow calling symbols in the main module call load with L_NOAUTODEFER and
 156 do a loadbind later with the main module.
 157
 158 D 1.3 92/12/27 20:59:55 jum 3 2 00066/00008/00342
 159 MRs:
 160 COMMENTS:
 161 added search by L_GETINFO if module got loaded by LIBPATH
 162
 163 D 1.2 92/08/16 17:45:43 jum 2 1 00074/00006/00276
 164 MRs:
 165 COMMENTS:
 166 implemented initialize and terminate functions, added reference counting to avoid multiple loads of the same library
 167
 168 D 1.1 92/08/02 18:08:45 jum 1 0 00282/00000/00000
 169 MRs:
 170 COMMENTS:
 171 Erstellungsdatum und -uhrzeit 92/08/02 18:08:45 von jum
 172