dlfcn(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
DLFCN(3)                  NetBSD Programmer's Manual                  DLFCN(3)


NAME

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


SYNOPSIS

     #include <dlfcn.h>

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

     int
     dlclose(void *handle);

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

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

     char *
     dlerror(void);


DESCRIPTION

     These functions provide an interface to the run-time linker ld.so.  They
     allow new shared objects to be loaded into the process' address space un-
     der program control.  The dlopen() function takes a name of a shared ob-
     ject 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 start-
     up. 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 library 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 object has already
     been loaded by a previous call to dlopen() (and not yet unloaded by
     dlclose()), a handle refering to the resident copy is returned.

     dlclose() unlinks and removes the object referred to by handle from the
     process address space. If multiple calls to have been done on this object
     (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.

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

     dlerror() return a character string representing the most recent error
     that has occurred while processing one of the other functions described
     here.


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.