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)