Standard C Library Functions dlsym(3C)
NAME
dlsym - get the address of a symbol in a shared object or
executable
SYNOPSIS
#include
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 exe-
cutable. The handle argument is either the value returned
from a call to dlopen() or one of a family of special han-
dles. 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 RTLDFIRST 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 sym-
bol 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.
RTLDEFAULT 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 fol-
lows the default model that is used to relo-
cate 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 sym-
bol. This loading compensates for objects
that have not fully defined their dependen-
cies. However, this compensation can under-
mine the advantages of lazy loading.
SunOS 5.11 Last change: 26 Sep 2005 1
Standard C Library Functions dlsym(3C)
RTLDPROBE Instructs dlsym() to search for the named
symbol in the same manner as occurs with a
handle of RTLDEFAULT. However, this model
only searches for symbols in the presently
loaded objects, together with any lazy load-
able 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 RTLDEFAULT.
RTLDNEXT Instructs dlsym() to search for the named
symbol in the objects that were loaded fol-
lowing the object from which the dlsym()
call is being made.
RTLDSELF 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 follow-
ing 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 RTLDGLOBAL mode.
RETURN VALUES
The dlsym() function returns NUL if handle does not refer
to a valid object opened by dlopen() or is not one of the
special handles. The function also returns NUL 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.
SunOS 5.11 Last change: 26 Sep 2005 2
Standard C Library Functions dlsym(3C)
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", RTLDLAZY);
/* find the address of function and data objects */
fptr = (int (*)(int))dlsym(handle, "myfunction");
iptr = (int *)dlsym(handle, "myobject");
/* 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 ver-
ify that a function is defined. If the function exists, the
function is called.
int (*fptr)();
if ((fptr = (int (*)())dlsym(RTLDEFAULT,
"myfunction")) != NUL) {
(*fptr)();
}
USAGE
The dlsym() function is one of a family of functions that
give the user direct access to the dynamic linking facili-
ties. These facilities are available to dynamically-linked
processes only. See the Linker and Libraries Guide.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 26 Sep 2005 3
Standard C Library Functions dlsym(3C)
ATRIBUTE TYPE ATRIBUTE 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(5), stan-
dards(5)
Linker and Libraries Guide
NOTES
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.
SunOS 5.11 Last change: 26 Sep 2005 4
|
