SunOS man pages : dlopen (3)
Dynamic Linking Library Functions dlopen(3DL)
NAME
dlopen, dlmopen - gain access to an executable object file
SYNOPSIS
cc [ flag ... ] file ... -ldl [ library ... ]
#include <dlfcn.h>
#include <link.h>
void * dlopen(const char *pathname, int mode);
void * dlmopen(Lmid_t lmid, const char *pathname, int mode);
DESCRIPTION
The dlopen() function makes an executable object file avail-
able to a running process. It returns to the process a han-
dle which the process may use on subsequent calls to dlsym()
and dlclose(). The value of this handle should not be inter-
preted in any way by the process. The pathname argument is
the path name of the object to be opened. A path name con-
taining an embedded '/' is interpreted as an absolute path
or relative to the current directory; otherwise, the set of
search paths currently in effect by the runtime linker will
be used to locate the specified file. See NOTES below.
Any dependencies recorded within pathname are also loaded as
part of the dlopen(). These dependencies are searched, in
the order they are loaded, to locate any additional depen-
dencies. This process will continue until all the dependen-
cies of pathname are loaded. This dependency tree is
referred to as a group.
If the value of pathname is 0, dlopen() provides a handle on
a global symbol object. This object provides access to the
symbols from an ordered set of objects consisting of the
original program image file, together with any dependencies
loaded at program startup, and any objects that were loaded
using dlopen() together with the RTLD_GLOBAL flag. As the
latter set of objects can change during process execution,
the set identified by handle can also change dynamically.
The dlmopen() function is identical to the dlopen() routine,
except that an identifying link-map id (lmid) is passed into
it. This link-map id informs the dynamic linking facilities
upon which link-map list to load the object. See Linker and
Libraries Guide
The mode argument describes how dlopen() will operate upon
pathname with respect to the processing of relocations and
the scope of visibility of the symbols provided by pathname
and its dependencies. When an object is brought into the
address space of a process, it may contain references to
symbols for which addresses are not known until the object
SunOS 5.8 Last change: 10 Dec 1999 1
Dynamic Linking Library Functions dlopen(3DL)
is loaded. These references must be relocated before the
symbols can be accessed. The mode argument governs when
these relocations take place and may have the following
values:
RTLD_LAZY
Only references to data symbols are relocated when the
object is first loaded. References to functions are
not relocated until a given function is invoked for
the first time. This mode should improve perfor-
mance, since a process may not reference all of the
functions in any given object. This behavior mimics
the normal loading of dependencies during process ini-
tialization.
RTLD_NOW
All necessary relocations are performed when the
object is first loaded. This may waste some process-
ing, if relocations are performed for functions that
are never referenced. This behavior may be useful for
applications that need to know as soon as an object is
loaded that all symbols referenced during execution
will be available. This option mimics the loading of
dependencies when the environment variable LD_BIND_NOW
is in effect.
To determine the scope of visibility for symbols loaded with
a dlopen() invocation, the mode parameter should be bitwise
or'ed with one of the following values:
RTLD_GLOBAL
The object's global symbols are made available for the
relocation processing of any other object. In addi-
tion, symbol lookup using dlopen(0, mode) and an asso-
ciated dlsym(), allows objects loaded with RTLD_GLOBAL
to be searched.
RTLD_LOCAL
The object's globals symbols are only available for
the relocation processing of other objects that
comprise the same group.
The program image file, and any objects loaded at program
startup, have the mode RTLD_GLOBAL. The mode RTLD_LOCAL is
the default mode for any objects acquired with dlopen(). A
local object may be a dependency of more then one group. Any
object of mode RTLD_LOCAL that is referenced as a dependency
of an object of mode RTLD_GLOBAL will be promoted to
RTLD_GLOBAL. In other words, the RTLD_LOCAL mode is ignored.
Any object loaded by dlopen() that requires relocations
against global symbols can reference the symbols in any
SunOS 5.8 Last change: 10 Dec 1999 2
Dynamic Linking Library Functions dlopen(3DL)
RTLD_GLOBAL object, which are at least the program image
file and any objects loaded at program startup, from the
object itself, and from any dependencies the object refer-
ences. However, the mode parameter may also be bitwise OR-ed
with the following values to affect the scope of symbol
availability:
RTLD_GROUP
Only symbols from the associated group are made avail-
able for relocation. A group is established from the
defined object and all the dependencies of that
object.
A group must be completely self-contained. All depen-
dency relationships between the members of the group
must be sufficient to satisfy the relocation require-
ments of each object that comprises the group.
RTLD_PARENT
The symbols of the object initiating the dlopen() call
are made available to the objects obtained by dlo-
pen() itself. This option is useful when hierarchical
dlopen() families are created. Note that although the
parent object can supply symbols for the relocation of
this object, the parent object is not available to
dlsym() through the returned handle.
RTLD_WORLD
Only symbols from RTLD_GLOBAL objects are made avail-
able for relocation.
The default modes for dlopen() are both RTLD_WORLD and
RTLD_GROUP. These modes are or'ed together if an object is
required by different dependencies specifying differing
modes.
The following modes provide additional capabilities outside
of relocation processing:
RTLD_NODELETE
The specified object will not be deleted from the
address space as part of a dlclose().
RTLD_NOLOAD
The specified object is not loaded as part of the dlo-
pen(), but a valid handle is returned if the object
already exists as part of the process address space.
Additional modes can be specified and will be or'ed
with the present mode of the object and its dependen-
cies. The RTLD_NOLOAD mode provides a means of query-
ing the presence, or promoting the modes, of an exist-
ing dependency.
SunOS 5.8 Last change: 10 Dec 1999 3
Dynamic Linking Library Functions dlopen(3DL)
The lmid passed to dlmopen() identifies the link-map list
where the object will be loaded. This can be any valid
Lmid_t returned by dlinfo() or one of the following special
values:
LM_ID_BASE
Load the object on the applications link-map list.
LM_ID_LDSO
Load the object on the dynamic linkers (ld.so.1)
link-map list.
LM_ID_NEWLM
Causes the object to create a new link-map list as
part of loading. It is vital that any object opened
on a new link-map list have all of its dependencies
expressed because there will be no other objects on
this link-map.
RETURN VALUES
If pathname cannot be found, cannot be opened for reading,
is not a shared or relocatable object, or if an error occurs
during the process of loading pathname or relocating its
symbolic references, dlopen() will return NULL. More
detailed diagnostic information will be available through
dlerror().
USAGE
The dlopen() and dlmopen() functions are members of a family
of functions that give the user direct access to the dynamic
linking facilities (see Linker and Libraries Guide) and are
available to dynamically-linked processes only.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
ld(1), ld.so.1(1), dladdr(3DL), dlclose(3DL), dldump(3DL),
dlerror(3DL), dlinfo(3DL), dlsym(3DL), attributes(5)
Linker and Libraries Guide
NOTES
SunOS 5.8 Last change: 10 Dec 1999 4
Dynamic Linking Library Functions dlopen(3DL)
If other objects were link-edited with pathname when path-
name was built, that is, the pathname has dependencies on
other objects, those objects will automatically be loaded by
dlopen(). The directory search path used to find both path-
name and the other needed objects may be affected by setting
the environment variable LD_LIBRARY_PATH, which is analyzed
once at process startup, and from a runpath setting within
the object from which the call to dlopen() originated. These
search rules will only be applied to path names that do not
contain an embedded '/'. Objects whose names resolve to the
same absolute or relative path name may be opened any number
of times using dlopen(); however, the object referenced
will only be loaded once into the address space of the
current process.
When loading shared objects the application should open a
specific version of the shared object, as opposed to relying
on the version of the shared object pointed to by the sym-
bolic link.
When building objects that are to be loaded on a new link-
map list (see LM_ID_NEWLM), some precautions need to be
taken. In general, all dependencies must be included when
building an object. Also, include /usr/lib/libmapmalloc.so.1
before /usr/lib/libc.so.1 when building an object.
When an object is loaded into memory on a new link-map list,
it is isolated from the main running program. There are
certain global resources that are only usable from one
link-map list. A few examples of these would be the sbrk()
based malloc(), libthread(), and the signal vectors.
Because of this, care must be taken not to use any of these
resources on any but the primary link-map list. These
issues are discussed in further detail in the Linker and
Libraries Guide
Some symbols defined in dynamic executables or shared
objects may not be available to the runtime linker. The sym-
bol table created by ld for use by the runtime linker might
contain only a subset of the symbols defined in the object.
SunOS 5.8 Last change: 10 Dec 1999 5
|
 |
|
|
