dlfcn(3) - NetBSD Manual Pages

DLFCN(3)                  NetBSD Programmer's Manual                  DLFCN(3)


NAME

     dlopen, dlclose, dlsym, dlctl, dlerror - dynamic link interface


SYNOPSIS

     #include <dlfcn.h>

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

     int
     dlclose(void *handle);

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

     int
     dladdr(void *addr, Dl_info *dli);

     int
     dlctl(void *handle, int cmd, void *data);

     char *
     dlerror(void);


DESCRIPTION

     These functions provide an interface to the run-time linker ld.so(1).
     They allow new shared objects to be loaded into the process' address
     space under program control.  The dlopen() function takes a name of a
     shared object as the first argument.  The shared object is mapped into
     the address space, relocated and its external references are resolved in
     the same way as is done with the implicitly loaded shared libraries at
     program startup.  The argument can either be an absolute pathname or it
     can be of the form ``lib<name>.so[.xx[.yy]]'' in which case the same li-
     brary search rules apply that are used for ``intrinsic'' shared library
     searches.  The second argument has currently no effect, but should be set
     to DL_LAZY for future compatibility.  dlopen() returns a handle to be
     used in calls to dlclose(), dlsym() and dlctl().  If the named shared ob-
     ject has already been loaded by a previous call to dlopen() (and not yet
     unloaded by dlclose()), a handle refering to the resident copy is re-
     turned.

     dlclose() unlinks and removes the object referred to by handle from the
     process address space.  If multiple calls to have been done on this ob-
     ject (or the object was one loaded at startup time) the object is removed
     when its reference count drops to zero.

     dlsym() looks for a definition of symbol in the shared object designated
     by handle.  The symbols address is returned.  If the symbol cannot be re-
     solved, NULL is returned.

     dladdr() examines all currently mapped shared objects for a symbol whose
     address -- as mapped in the proces address space -- is closest to but not
     exceeding the value passed in the first argument addr.  The symbols of a
     shared object are only eligible if addr is between the base address of
     the shared object and the value of the symbol ``_end'' in the same shared
     object. If no object for which this condition holds true can be found,
     dladdr() will return 0. Otherwise, a non-zero value is returned and the
     dli argument will be used to provide information on the selected symbol
     and the shared object it is contained in.  The dli argument points at a
     caller-provided Dl_info structure defined as follows:

           typedef struct {
                   const char  *dli_fname;     /* File defining the symbol */
                   void        *dli_fbase;     /* Base address */
                   const char  *dli_sname;     /* Symbol name */
                   void        *dli_saddr;     /* Symbol address */
           } Dl_info;

     The member dli_sname points at the nul-terminated name of the selected
     symbol, and dli_saddr is the actual address (as it appears in the process
     address space) of the symbol.  The member dli_fname points at the file
     name corresponding to the shared object in which the symbol was found,
     while dli_fbase is the base address at which this shared object is loaded
     in the process address space.  dli_fname and dli_fbase may be zero if the
     symbol was found in the internally generated ``copy'' section (see
     link(5)) which is not associated with a file.  Note: both strings pointed
     at by dli_fname and dli_sname reside in memory private to the run-time
     linker module and should not be modified by the caller.

     dlctl() provides an interface similar to ioctl(2) to control several as-
     pects of the run-time linker's operation.  This interface is currently
     under development.

     dlerror() return a character string representing the most recent error
     that has occurred while processing one of the other functions described
     here.  If no dynamic linking errors have occured since the last invoca-
     tion of dlerror(), dlerror() returns NULL.  Thus, invoking dlerror() a
     second time, immediately following a prior invocation, will result in
     NULL being returned.


SEE ALSO

     ld(1), rtld(1), link(5)


HISTORY

     Some of the dl* functions first appeared in SunOS 4.


BUGS

     An error that occurs while processing a dlopen() request results in the
     termination of the program.

NetBSD 1.4                    September 30, 1995                             2