DLFCN(3)                  OpenBSD 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, 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 a process's address space un-
     der program control.

     The dlopen() function takes a name of a shared object as its first argu-
     ment.  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 path 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 currently has 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 previ-
     ous call to dlopen() (and not yet unloaded by dlclose()), a handle refer-
     ring 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 dlopen() have been done on
     this object (or the object was once 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 symbol's 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
     under development.

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

SEE ALSO
     ld(1), ld.so(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.

OpenBSD 2.8                   September 30, 1995                             2
