dlsym(3)dlsym(3)NAMEdlsym - obtain the address of a symbol from a dlopen() object
SYNOPSIS
#include <dlfcn.h>
void *dlsym(
void *handle,
const char *name );
PARAMETERS
The value returned from a call to dlopen() (and which has not since
been released by a call to dlclose()). The name (character string) of
the symbol being sought.
DESCRIPTION
The dlsym() function allows a process to obtain the address of a symbol
defined within an object made accessible by a dlopen() call.
The dlsym() function will search for the named symbol in all objects
loaded automatically as a result of loading the object referenced by
handle (see dlopen(3)). Load ordering is used in dlsym() operations
upon the global symbol object. The symbol resolution algorithm used
will be in dependency order as described in dlopen(3).
NOTES
Use of the dlsym() routine is the preferred mechanism for retrieving
symbol addresses. This routine reliably returns the current address of
a symbol at any point in the program, while the dynamic symbol resolu‐
tion described previously might not function as expected due to com‐
piler optimizations. For example, the address of a symbol might be
saved in a register prior to a dlopen() call, and the saved address
might then be used after the dlopen() call -- even if the dlopen() call
changed the resolution of the symbol.
ERRORS
No errors are defined.
RETURN VALUE
The dlsym() function will return NULL if handle does not refer to a
valid object opened by dlopen() or if the named symbol cannot be found
within any of the objects associated with handle. More detailed diag‐
nostic information is available through dlerror().
APPLICATION USAGE
Special-purpose values for handle are reserved for future use. These
values and their meanings are: Specifies the next object after this one
that defines name. This one refers to the object containing the invoca‐
tion of dlsym(). The next object is the one found upon the application
of a load order symbol resolution algorithm (see dlopen(3)). The next
object is either one of global scope -- because it was introduced as
part of the original process image or because it was added with a
dlopen() operation including the RTLD_GLOBAL option -- or an object
that was included in the same dlopen() operation that loaded this one.
The RTLD_NEXT option is useful to navigate an intentionally created
hierarchy of multiply defined symbols created through interposition.
For example, if a program wished to create an implementation of mal‐
loc() that embedded some statistics gathering about memory allocations,
such an implementation could use the real malloc() definition to per‐
form the memory allocation -- and itself only embed the necessary logic
to implement the statistics gathering function.
EXAMPLES
The following example shows how one can 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);
SEE ALSOdlclose(3), dlerror(3), dlopen(3).
dlsym(3)