DLSYM(3C) Standard C Library Functions DLSYM(3C)
NAME
dlsym - get the address of a symbol in a shared object or executable
SYNOPSIS
#include <dlfcn.h>
void *dlsym(
void *restrict handle,
const char *restrict name);
DESCRIPTION
The
dlsym() function allows a process to obtain the address of a symbol
that is defined within a shared object or executable. The
handle argument
is either the value returned from a call to
dlopen() or one of a family
of special handles. The
name argument is the symbol's name as a character
string.
If
handle is returned from
dlopen(), the associated shared object must
not have been closed using
dlclose(). A
handle can be obtained from
dlopen() using the
RTLD_FIRST mode. With this mode, the
dlsym() function
searches for the named symbol in the initial object referenced by
handle.
Without this mode, the
dlsym() function searches for the named symbol in
the group of shared objects loaded automatically as a result of loading
the object referenced by
handle. See
dlopen(3C) and NOTES.
The following special handles are supported.
RTLD_DEFAULT Instructs
dlsym() to search for the named symbol starting
with the first object loaded, typically the dynamic
executable. The search continues through the list of
initial dependencies that are loaded with the process,
followed by any objects obtained with
dlopen(3C). This
search follows the default model that is used to relocate
all objects within the process.
This model also provides for transitioning into a lazy
loading environment. If a symbol can not be found in the
presently loaded objects, any pending lazy loaded objects
are processed in an attempt to locate the symbol. This
loading compensates for objects that have not fully
defined their dependencies. However, this compensation
can undermine the advantages of lazy loading.
RTLD_PROBE Instructs
dlsym() to search for the named symbol in the
same manner as occurs with a
handle of
RTLD_DEFAULT.
However, this model only searches for symbols in the
presently loaded objects, together with any lazy loadable
objects specifically identified by the caller to provide
the named symbol. This handle does not trigger an
exhaustive load of any lazy loadable symbols in an
attempt to find the named symbol. This handle can provide
a more optimal search than would occur using
RTLD_DEFAULT.
RTLD_NEXT Instructs
dlsym() to search for the named symbol in the
objects that were loaded following the object from which
the
dlsym() call is being made.
RTLD_SELF Instructs
dlsym() to search for the named symbol in the
objects that were loaded starting with the object from
which the
dlsym() call is being made.
When used with a special handle,
dlsym() is selective in searching
objects that have been loaded using
dlopen(). These objects are searched
for symbols if one of the following conditions are true.
o The object is part of the same local
dlopen() dependency
hierarchy as the calling object. See the
Linker and Libraries Guide for a description of
dlopen() dependency hierarchies.
o The object has global search access. See
dlopen(3C) for a
discussion of the
RTLD_GLOBAL mode.
RETURN VALUES
The
dlsym() function returns
NULL if
handle does not refer to a valid
object opened by
dlopen() or is not one of the special handles. The
function also returns
NULL if the named symbol cannot be found within any
of the objects associated with
handle. Additional diagnostic information
is available through
dlerror(3C).
EXAMPLES
Example 1: Use dlopen() and dlsym() to access a function or data objects.
The following code fragment demonstrates how to use
dlopen() and
dlsym() to access either function or data objects. For simplicity, error checking
has been omitted.
void *handle;
int *iptr, (*fptr)(int);
/* open the needed object */
handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_LAZY);
/* find the address of function and data objects */
fptr = (int (*)(int))dlsym(handle, "my_function");
iptr = (int *)dlsym(handle, "my_object");
/* invoke function, passing value of integer as a parameter */
(*fptr)(*iptr);
Example 2: Use dlsym() to verify that a particular function is defined.
The following code fragment shows how to use
dlsym() to verify that a
function is defined. If the function exists, the function is called.
int (*fptr)();
if ((fptr = (int (*)())dlsym(RTLD_DEFAULT,
"my_function")) != NULL) {
(*fptr)();
}
USAGE
The
dlsym() function is one of a family of functions that give the user
direct access to the dynamic linking facilities. These facilities are
available to dynamically-linked processes only. See the
Linker and Libraries Guide.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
SEE ALSO
ld(1),
ld.so.1(1),
dladdr(3C),
dlclose(3C),
dldump(3C),
dlerror(3C),
dlinfo(3C),
dlopen(3C),
attributes(7),
standards(7) Linker and Libraries GuideNOTES
If an object is acting as a filter, care should be taken when
interpreting the address of any symbol obtained using a handle to this
object. For example, using
dlsym(3C) to obtain the symbol
_end for this
object, results in returning the address of the symbol
_end within the
filtee, not the filter. For more information on filters see the
Linker and Libraries Guide.
September 26, 2005
DLSYM(3C)