March 31, 2008 DLFCN 3

### NAME

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

### LIBRARY

(These functions are not in a library. They are included in every dynamically linked program automatically.)

### SYNOPSIS

```void *` dlopen(```const char *path``, int mode`)
```int` dlclose(```void *handle`)
```void *` dlsym(```void * restrict handle``, const char * restrict symbol`)
```int` dladdr(```void * restrict addr``, Dl_info * restrict 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 ``<Xo lib name .so > [.xx[ .yy Xc]]'' in which case the same library search rules apply that are used for ``intrinsic'' shared library searches. If the first argument is ```NULL`, dlopen(``) returns a handle on the global symbol object. This object provides access to all symbols from an ordered set of objects consisting of the original program image and any dependencies loaded during startup.

The second argument has currently no effect, but should be set to ```RTLD_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 bydlclose(``)), a handle referring 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 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 resolved, ```NULL` is returned.

dladdr(``) examines all currently mapped shared objects for a symbol whose address -- as mapped in the process 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 */
              const 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 link(5) (see) 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 aspects of the run-time linker's operation. This interface is

dlerror(``) returns 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 occurred since the last invocation 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.