Copyright (c) 1992,1993,1995, Jens-Uwe Mager, Helios Software GmbH

Not derived from licensed software.

Permission is granted to freely use, copy, modify, and redistribute

this software, provided that no attempt is made to gain profit from it,

the author is not construed to be liable for any results of using the

software, alterations are clearly marked as such, and this notice is

not modified.

libdl.a

-------

This is an emulation library to emulate the SunOS/System V.4 functions

to access the runtime linker. The functions are emulated by using the

AIX load() function and by reading the .loader section of the loaded

module to find the exports. The to be loaded module should be linked as

follows (if using AIX 3):

cc -o module.so -bM:SRE -bE:module.exp -e _nostart $(OBJS)

For AIX 4:

cc -o module.so -bM:SRE -bE:module.exp -bnoentry $(OBJS)

The module export file contains the symbols to be exported. Because

this library uses the loader section, the final module.so file can be

stripped. C++ users should build their shared objects using the script

makeC++SharedLib (part of the IBM C++ compiler), this will make sure

that constructors and destructors for static and global objects will be

called upon loading and unloading the module.

Usage

-----

void *dlopen(const char *path, int mode);

This routine loads the module pointed to by path and reads its export

table. If the path does not contain a '/' character, dlopen will search

for the module using the LIBPATH environment variable. It returns an

opaque handle to the module or NULL on error. The mode parameter can be

either RTLD_LAZY (for lazy function binding) or RTLD_NOW for immediate

function binding. The AIX implementation currently does treat RTLD_NOW

the same as RTLD_LAZY. The flag RTLD_GLOBAL might be or'ed into the

mode parameter to allow loaded modules to bind to global variables or

functions in other loaded modules loaded by dlopen(). If RTLD_GLOBAL is

not specified, only globals from the main part of the executable or

shared libraries are used to look for undefined symbols in loaded

modules.

void *dlsym(void *handle, const char *symbol);

This routine searches for the symbol in the module referred to by

handle and returns its address. If the symbol could not be found, the

function returns NULL. The return value must be casted to a proper

function pointer before it can be used. SunOS/System V.4 allow handle

to be a NULL pointer to refer to the module the call is made from, this

is not implemented.

int dlclose(void *handle);

This routine unloads the module referred to by the handle and disposes

of any local storage. this function returns -1 on failure.

char *dlerror(void);

This routine can be used to retrieve a text message describing the most

recent error that occured on on of the above routines. This function

returns NULL if there is not error information.

Initialization and termination handlers

---------------------------------------

The emulation provides for an initialization and a termination

handler. The dlfcn.h file contains a structure declaration named

dl_info with following members:

void (*init)(void);

void (*fini)(void);

The init function is called upon first referencing the library. The

fini function is called at dlclose() time or when the process exits.

The module should declare a variable named dl_info that contains this

structure which must be exported. These functions correspond to the

documented _init() and _fini() functions of SunOS 4.x, but these are

appearently not implemented in SunOS. When using SunOS 5.0, these

correspond to #pragma init and #pragma fini respectively. At the same

time any static or global C++ object's constructors or destructors will

be called.

Jens-Uwe Mager

HELIOS Software GmbH

Lavesstr. 80

30159 Hannover

Germany

Phone:+49 511 36482-0

FAX:+49 511 36482-69

AppleLink:helios.deAttn: Jens-Uwe Mager

Internet:jum@helios.de

Revison History

---------------

SCCS/s.dlfcn.h:

D 1.4 95/04/25 09:36:52 jum 4 300018/00004/00028

MRs:

COMMENTS:

added RTLD_GLOBAL, include and C++ guards

D 1.3 92/12/27 20:58:32 jum 3 200001/00001/00031

MRs:

COMMENTS:

we always have prototypes on RS/6000

D 1.2 92/08/16 17:45:11 jum 2 100009/00000/00023

MRs:

COMMENTS:

added dl_info structure to implement initialize and terminate functions

D 1.1 92/08/02 18:08:45 jum 1 000023/00000/00000

MRs:

COMMENTS:

Erstellungsdatum und -uhrzeit 92/08/02 18:08:45 von jum

SCCS/s.dlfcn.c:

D 1.7 95/08/14 19:08:38 jum 8 600026/00004/00502

MRs:

COMMENTS:

Integrated the fixes from Kirk Benell (kirk@rsinc.com) to allow loading of

shared objects generated under AIX 4. Fixed bug that symbols with exactly

8 characters would use garbage characters from the following symbol value.

D 1.6 95/04/25 09:38:03 jum 6 500046/00006/00460

MRs:

COMMENTS:

added handling of C++ static constructors and destructors, added RTLD_GLOBAL to bind against other loaded modules

D 1.5 93/02/14 20:14:17 jum 5 400002/00000/00464

MRs:

COMMENTS:

added path to dlopen error message to make clear where there error occured.

D 1.4 93/01/03 19:13:56 jum 4 300061/00005/00403

MRs:

COMMENTS:

to allow calling symbols in the main module call load with L_NOAUTODEFER and

do a loadbind later with the main module.

D 1.3 92/12/27 20:59:55 jum 3 200066/00008/00342

MRs:

COMMENTS:

added search by L_GETINFO if module got loaded by LIBPATH

D 1.2 92/08/16 17:45:43 jum 2 100074/00006/00276

MRs:

COMMENTS:

implemented initialize and terminate functions, added reference counting to avoid multiple loads of the same library

D 1.1 92/08/02 18:08:45 jum 1 000282/00000/00000

MRs:

COMMENTS:

Erstellungsdatum und -uhrzeit 92/08/02 18:08:45 von jum