.SH SYNOPSIS
.nf
.B #include <dlfcn.h>
-.PP
+.P
.BI "void *dlopen(const char *" filename ", int " flags );
.BI "int dlclose(void *" handle );
-.PP
+.P
.B #define _GNU_SOURCE
.br
.B #include <dlfcn.h>
-.PP
+.P
.BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags );
.fi
.SH DESCRIPTION
.BR dlinfo (3),
and
.BR dlclose ().
-.PP
+.P
If
.I filename
.\" FIXME On Solaris, when handle is NULL, we seem to get back
and
.I /usr/lib
are searched (in that order).
-.PP
+.P
If the object specified by
.I filename
has dependencies on other shared objects,
using the same rules.
(This process may occur recursively,
if those objects in turn have dependencies, and so on.)
-.PP
+.P
One of the following two values must be included in
.IR flags :
.TP
.BR dlopen ()
returns.
If this cannot be done, an error is returned.
-.PP
+.P
Zero or more of the following values may also be ORed in
.IR flags :
.TP
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.
-.PP
+.P
If
.I filename
is NULL, then the returned handle is for the main program.
.BR dlopen ()
with the flag
.BR RTLD_GLOBAL .
-.PP
+.P
Symbol references in the shared object are resolved using (in order):
symbols in the link map of objects loaded for the main program and its
dependencies;
flag;
and definitions in the shared object itself
(and any dependencies that were loaded for that object).
-.PP
+.P
Any global symbols in the executable that were placed into
its dynamic symbol table by
.BR ld (1)
or because
.BR ld (1)
noted a dependency on a symbol in another object during static linking.
-.PP
+.P
If the same shared object is opened again with
.BR dlopen (),
the same object handle is returned.
has succeeded on it.
Constructors (see below) are called only when the object is actually loaded
into memory (i.e., when the reference count increases to 1).
-.PP
+.P
A subsequent
.BR dlopen ()
call that loads the same shared object with
.B RTLD_GLOBAL
in a subsequent
.BR dlopen ().
-.PP
+.P
If
.BR dlopen ()
fails for any reason, it returns NULL.
.I flags
arguments, as well as the return value, are the same,
except for the differences noted below.
-.PP
+.P
The
.BR dlmopen ()
function differs from
The
.I Lmid_t
type is an opaque handle that refers to a namespace.
-.PP
+.P
The
.I lmid
argument is either the ID of an existing 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.
-.PP
+.P
If
.I filename
is NULL, then the only permitted value for
decrements the reference count on the
dynamically loaded shared object referred to by
.IR handle .
-.PP
+.P
If the object's reference count drops to zero
and no symbols in this object are required by other objects,
then the object is unloaded
because this object was opened with the
.B RTLD_GLOBAL
flag and one of its symbols satisfied a relocation in another object.)
-.PP
+.P
All shared objects that were automatically loaded when
.BR dlopen ()
was invoked on the object referred to by
.I handle
are recursively closed in the same manner.
-.PP
+.P
A successful return from
.BR dlclose ()
does not guarantee that the symbols associated with
(file could not be found, was not readable, had the wrong format,
or caused errors during loading),
these functions return NULL.
-.PP
+.P
On success,
.BR dlclose ()
returns 0; on error, it returns a nonzero value.
-.PP
+.P
Errors from these functions can be diagnosed using
.BR dlerror (3).
.SH ATTRIBUTES
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.
-.PP
+.P
The
.BR dlmopen ()
function permits object-load isolation\[em]the ability
This can be achieved by using a separate namespace and the
.B RTLD_GLOBAL
flag.
-.PP
+.P
The
.BR dlmopen ()
function also can be used to provide better isolation than the
.B 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.
-.PP
+.P
Possible uses of
.BR dlmopen ()
are plugins where the author of the plugin-loading framework
.BR dlmopen (),
this can be achieved by loading the same shared object file into
different namespaces.
-.PP
+.P
The glibc implementation supports a maximum of
.\" DL_NNS
16 namespaces.
info pages (under "Function attributes")
.\" info gcc "C Extensions" "Function attributes"
for further information.
-.PP
+.P
An older method of (partially) achieving the same result is via the use of
two special symbols recognized by the linker:
.B _init
.BR gcc (1)
.I \-nostartfiles
command-line option.
-.PP
+.P
Use of
.B _init
and
.\" .\" void _init(void) __attribute__((constructor));
.\" .\" void _fini(void) __attribute__((destructor));
.\"
-.PP
+.P
Since glibc 2.2.3,
.BR atexit (3)
can be used to register an exit handler that is automatically
.BR cos (3)
function, and prints the cosine of 2.0.
The following is an example of building and running the program:
-.PP
+.P
.in +4n
.EX
$ \fBcc dlopen_demo.c \-ldl\fP
.BR rtld\-audit (7),
.BR ld.so (8),
.BR ldconfig (8)
-.PP
+.P
gcc info pages, ld info pages
projects / thirdparty / man-pages.git / blobdiff