DLOPEN(3) | Library Functions Manual | DLOPEN(3)

# NAME

`dlopen`, `dlclose`, `dlsym`, `dladdr`, `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`(const void *addr, Dl_info *info);

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 a process's address space under program control.

The `dlopen`() function takes the name of a shared object as its 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 path parameter can be specified as either an absolute pathname to a shared library or just the name of the shared library itself. When an absolute pathname is specified, only the path provided will be searched for the shared library. When just a shared library is specified, the same paths will be searched that are used for “intrinsic” shared library searches.

Shared libraries take the following form:

`lib<name>.so[.xx[.yy]]`

When a shared library is specified without a version or with a partial version, the same library search rules apply that are used for “intrinsic” shared library searches. A null pointer supplied for path will return a special handle that behaves the same as the `RTLD_DEFAULT` special handle.

The mode parameter specifies symbol resolution time and symbol visibility. One of the following values may be used to specify symbol resolution time:

RTLD_NOW
  Symbols are resolved immediately.
RTLD_LAZY
  Symbols are resolved when they are first referred to. This is the default value if resolution time is unspecified.

One of the following values may be used to specify symbol visibility:

RTLD_GLOBAL
  The object's symbols and the symbols of its dependencies will be visible to other objects.
RTLD_LOCAL
  The object's symbols and the symbols of its dependencies will not be visible to other objects. This is the default value if visibility is unspecified.

To specify both resolution time and visibility, bitwise inclusive OR one of each of the above values together. If an object was opened with RTLD_LOCAL and later opened with RTLD_GLOBAL, then it is promoted to RTLD_GLOBAL.

Additionally, the following flag may be ORed into the mode argument:

RTLD_NODELETE
  Prevents unload of the loaded object on `dlclose`().
RTLD_NOLOAD
  Only return valid handle for the object if it is already loaded in the process address space, otherwise NULL is returned. Other mode flags may be specified, which will be applied for promotion for the found object.

The main executable's symbols are normally invisible to `dlopen`() symbol resolution. Those symbols will be visible if linking is done with cc(1) `-rdynamic`, which is equivalent to ld(1) `--export-dynamic`.

All shared objects loaded at program startup are globally visible.

`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 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 is a dependency of another object then the object is removed when its reference count drops to zero. `dlclose`() returns 0 on success and non-zero on failure.

`dlsym`() searches for a definition of symbol in the object designated by handle and all shared objects that it depends on. The symbol's address is returned. If the symbol cannot be resolved, `NULL` is returned.

`dlsym`() may also be called with special handles. `dlsym`() respects symbol visibility as specified by the `dlopen`() mode parameter. However, the symbols of an object's dependencies are always visible to it. The following special handles may be used with `dlsym`():

NULL
  Interpreted as a reference to the executable or shared object from which the call is being made. Thus an object can reference its own symbols and the symbols of its dependencies without calling `dlopen`().
RTLD_DEFAULT
  All the visible shared objects and the executable will be searched in the order they were loaded.
RTLD_NEXT
  The search for symbol is limited to the visible shared objects which were loaded after the one issuing the call to `dlsym`(). Thus, if `dlsym`() is called from the main program, all the visible shared libraries are searched. If it is called from a shared library, all subsequently visible shared libraries are searched.
RTLD_SELF
  The search for symbol is limited to the shared object issuing the call to `dlsym`() and those shared objects which were loaded after it that are visible.

`dladdr`() queries the dynamic linker for information about the shared object containing the address addr. The information is returned in the structure specified by info. The structure contains at least the following members:

`const char *dli_fname`
  The pathname of the shared object containing the address addr.
`void *dli_fbase`
  The base address at which the shared object is mapped into the address space of the calling process.
`const char *dli_sname`
  The name of the nearest run-time symbol with an address less than or equal to addr.

  If no symbol with a suitable address is found, both this field and dli_saddr are set to `NULL`.

`void *dli_saddr`
  The address of the symbol returned in dli_sname.

If a mapped shared object containing addr cannot be found, `dladdr`() returns 0. In that case, a message detailing the failure can be retrieved by calling `dlerror`(). On success, a non-zero value is returned. 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.

In dynamically linked programs, the address of a global function will point to its program linkage table entry, rather than to the entry point of the function itself. This causes most global functions to appear to be defined within the main executable, rather than in the shared libraries where the actual code resides.

`dlctl`() provides an interface similar to ioctl(2) to control several aspects 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. 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), ld.so(1), elf(5)

# STANDARDS

The `dladdr`(), `dlclose`(), `dlerror`(), `dlopen`(), and `dlsym`() functions conform to.

# HISTORY

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

# CAVEATS

Loading untrustworthy libraries into the process's address space with `dlopen` is very dangerous because system-dependent initialization steps occur including the calling of constructor functions, even if the library is otherwise unused.

June 13, 2025 | Debian