DESCRIPTION

dlopen()

The function
dlopen()
loads the dynamic shared object (shared library)
file named by the null-terminated
string
filename
and returns an opaque "handle" for the loaded object.
This handle is employed with other functions in the dlopen API, such as
dlsym(3),
dladdr(3),
dlinfo(3),
and
dlclose().

If
filename
is NULL, then the returned handle is for the main program.
If
filename
contains a slash ("/"), then it is interpreted as a (relative
or absolute) pathname.
Otherwise, the dynamic linker searches for the object as follows
(see
ld.so(8)
for further details):

o

(ELF only) If the executable file for the calling program
contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag,
then the directories listed in the DT_RPATH tag are searched.

o

If, at the time that the program was started, the environment variable
LD_LIBRARY_PATH
was defined to contain a colon-separated list of directories,
then these are searched.
(As a security measure, this variable is ignored for set-user-ID and
set-group-ID programs.)

o

(ELF only) If the executable file for the calling program
contains a DT_RUNPATH tag, then the directories listed in that tag
are searched.

o

The cache file
/etc/ld.so.cache
(maintained by
ldconfig(8))
is checked to see whether it contains an entry for
filename.

o

The directories
/lib
and
/usr/lib
are searched (in that order).

If the object specified by
filename
has dependencies on other shared objects,
then these are also automatically loaded by the dynamic linker
using the same rules.
(This process may occur recursively,
if those objects in turn have dependencies, and so on.)

One of the following two values must be included in
flags:

RTLD_LAZY

Perform lazy binding.
Resolve symbols only as the code that references them is executed.
If the symbol is never referenced, then it is never resolved.
(Lazy binding is performed only for function references;
references to variables are always immediately bound when
the shared object is loaded.)
Since glibc 2.1.1,
this flag is overridden by the effect of the
LD_BIND_NOW
environment variable.

RTLD_NOW

If this value is specified, or the environment variable
LD_BIND_NOW
is set to a nonempty string,
all undefined symbols in the shared object are resolved before
dlopen()
returns.
If this cannot be done, an error is returned.

Zero or more of the following values may also be ORed in
flags:

RTLD_GLOBAL

The symbols defined by this shared object will be
made available for symbol resolution of subsequently loaded shared objects.

RTLD_LOCAL

This is the converse of
RTLD_GLOBAL,
and the default if neither flag is specified.
Symbols defined in this shared object are not made available to resolve
references in subsequently loaded shared objects.

RTLD_NODELETE (since glibc 2.2)

Do not unload the shared object during
dlclose().
Consequently, the object's static variables are not reinitialized
if the object is reloaded with
dlopen()
at a later time.

RTLD_NOLOAD (since glibc 2.2)

Don't load the shared object.
This can be used to test if the object is already resident
(dlopen()
returns NULL if it is not, or the object's handle if it is resident).
This flag can also be used to promote the flags on a shared object
that is already loaded.
For example, a shared object that was previously loaded with
RTLD_LOCAL
can be reopened with
RTLD_NOLOAD | RTLD_GLOBAL.

RTLD_DEEPBIND (since glibc 2.3.4)

Place the lookup scope of the symbols in this
shared object ahead of the global scope.
This means that a self-contained object will use
its own symbols in preference to global symbols with the same name
contained in objects that have already been loaded.

If
filename
is NULL, then the returned handle is for the main program.
When given to
dlsym(),
this handle causes a search for a symbol in the main program,
followed by all shared objects loaded at program startup,
and then all shared objects loaded by
dlopen()
with the flag
RTLD_GLOBAL.

External references in the shared object are resolved using the
shared objects in that object's dependency list and any other
objects previously opened with the
RTLD_GLOBAL
flag.
If the executable was linked with the flag "-rdynamic"
(or, synonymously, "--export-dynamic"),
then the global symbols in the executable will also be used
to resolve references in a dynamically loaded shared object.

If the same shared object is loaded again with
dlopen(),
the same object handle is returned.
The dynamic linker maintains reference
counts for object handles, so a dynamically loaded shared object is not
deallocated until
dlclose()
has been called on it as many times as
dlopen()
has succeeded on it.
Any initialization returns (see below) are called just once.
However, a subsequent
dlopen()
call that loads the same shared object with
RTLD_NOW
may force symbol resolution for a shared object earlier loaded with
RTLD_LAZY.

If
dlopen()
fails for any reason, it returns NULL.

dlmopen()

This function performs the same task as
dlopen()---the
filename
and
flags
arguments, as well as the return value, are the same,
except for the differences noted below.

The
dlmopen()
function differs from
dlopen()
primarily in that it accepts an additional argument,
lmid,
that specifies the link-map list (also referred to as a
namespace)
in which the shared object should be loaded.
(By comparison,
dlopen()
adds the dynamically loaded shared object to the same namespace as
the shared object from which the
dlopen()
call is made.)
The
Lmid_t
type is an opaque handle that refers to a namespace.

The
lmid
argument is either the ID of an existing namespace
(which can be obtained using the
dlinfo(3)
RTLD_DI_LMID
request) or one of the following special values:

LM_ID_BASE

Load the shared object in the initial namespace
(i.e., the application's namespace).

LM_ID_NEWLM

Create a new namespace and load the shared object in that namespace.
The object must have been correctly linked
to reference all of the other shared objects that it requires,
since the new namespace is initially empty.

If
filename
is NULL, then the only permitted value for
lmid
is
LM_ID_BASE.

dlclose()

The function
dlclose()
decrements the reference count on the
dynamically loaded shared object referred to by
handle.
If the reference count drops to zero,
then the object is unloaded.
All shared objects that were automatically loaded when
dlopen()
was invoked on the object referred to by
handle
are recursively closed in the same manner.

A successful return from
dlclose()
does not guarantee that the symbols associated with
handle
are removed from the caller's address space.
In addition to references resulting from explicit
dlopen()
calls, a shared object may have been implicitly loaded
(and reference counted) because of dependencies in other shared objects.
Only when all references have been released can the shared object
be removed from the address space.

RETURN VALUE

On success,
dlopen()
and
dlmopen()
return a non-NULL handle for the loaded library.
On error
(file could not be found, was not readable, had the wrong format,
or caused errors during loading),
these functions return NULL.

On success,
dlclose()
returns 0; on error, it returns a nonzero value.

VERSIONS

dlopen()
and
dlclose()
are present in glibc 2.0 and later.
dlmopen()
first appeared in glibc 2.3.4.

ATTRIBUTES

For an explanation of the terms used in this section, see
attributes(7).

Interface

Attribute

Value

dlopen(),
dlmopen(),
dlclose()

Thread safety

MT-Safe

CONFORMING TO

POSIX.1-2001 describes
dlclose()
and
dlopen().
The
dlmopen()
function is a GNU extension.

The
RTLD_NOLOAD,
RTLD_NODELETE,
and
RTLD_DEEPBIND
flags are GNU extensions;
the first two of these flags are also present on Solaris.

NOTES

dlmopen() and namespaces

A link-map list defines an isolated namespace for the
resolution of symbols by the dynamic linker.
Within a namespace,
dependent shared objects are implicitly loaded according to the usual rules,
and symbol references are likewise resolved according to the usual rules,
but such resolution is confined to the definitions provided by the
objects that have been (explicitly and implicitly) loaded into the namespace.

The
dlmopen()
function permits object-load isolation---the ability
to load a shared object in a new namespace without
exposing the rest of the application to the symbols
made available by the new object.
Note that the use of the
RTLD_LOCAL
flag is not sufficient for this purpose,
since it prevents a shared object's symbols from being available to
any
other shared object.
In some cases,
we may want to make the symbols provided by a dynamically
loaded shared object available to (a subset of) other shared objects
without exposing those symbols to the entire application.
This can be achieved by using a separate namespace and the
RTLD_GLOBAL
flag.

The
dlmopen()
function also can be used to provide better isolation than the
RTLD_LOCAL
flag.
In particular, shared objects loaded with
RTLD_LOCAL
may be promoted to
RTLD_GLOBAL
if they are dependencies of another shared object loaded with
RTLD_GLOBAL.
Thus,
RTLD_LOCAL
is insufficient to isolate a loaded shared object except in the (uncommon)
case where one has explicit control over all shared object dependencies.

Possible uses of
dlmopen()
are plugins where the author of the plugin-loading framework
can't trust the plugin authors and does not wish
any undefined symbols from the plugin framework to be resolved to plugin
symbols.
Another use is to load the same object more than once.
Without the use of
dlmopen(),
this would require the creation of distinct copies of the shared object file.
Using
dlmopen(),
this can be achieved by loading the same shared object file into
different namespaces.

The glibc implementation supports a maximum of
16 namespaces.

Initialization and finalization functions

Shared objects may export functions using the
__attribute__((constructor))
and
__attribute__((destructor))
function attributes.
Constructor functions are executed before
dlopen()
returns, and destructor functions are executed before
dlclose()
returns.
A shared object may export multiple constructors and destructors,
and priorities can be associated with each function
to determine the order in which they are executed.
See the
gcc
info pages (under "Function attributes")
for further information.

An older method of (partially) achieving the same result is via the use of
two special symbols recognized by the linker:
_init
and
_fini.
If a dynamically loaded shared object exports a routine named
_init(),
then that code is executed after loading a shared object, before
dlopen()
returns.
If the shared object exports a routine named
_fini(),
then that routine is called just before the object is unloaded.
In this case, one must avoid linking against the system startup files,
which contain default versions of these files;
this can be done by using the
gcc(1)
-nostartfiles
command-line option.

Use of
_init
and
_fini
is now deprecated in favor of the aforementioned
constructors and destructors,
which among other advantages,
permit multiple initialization and finalization functions to be defined.

Since glibc 2.2.3,
atexit(3)
can be used to register an exit handler that is automatically
called when a shared object is unloaded.

History

These functions are part of the dlopen API, derived from SunOS.

BUGS

As at glibc 2.24, specifying the
RTLD_GLOBAL
flag when calling
dlmopen()
generates an error.
Furthermore, specifying
RTLD_GLOBAL
when calling
dlopen()
results in a program crash
(SIGSEGV)
if the call is made from any object loaded in a
namespace other than the initial namespace.

EXAMPLE

The program below loads the (glibc) math library,
looks up the address of the
cos(3)
function, and prints the cosine of 2.0.
The following is an example of building and running the program:

/* According to the ISO C standard, casting between function
pointers and 'void *', as done above, produces undefined results.
POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and
proposed the following workaround:

*(void **) (&cosine) = dlsym(handle, "cos");

This (clumsy) cast conforms with the ISO C standard and will
avoid any compiler warnings.

The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a.
POSIX.1-2013) improved matters by requiring that conforming
implementations support casting 'void *' to a function pointer.
Nevertheless, some compilers (e.g., gcc with the '-pedantic'
option) may complain about the cast used in this program. */

SEE ALSO

COLOPHON

This page is part of release 4.13 of the Linux
man-pages
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
https://www.kernel.org/doc/man-pages/.