dlsym(3) Library Functions Manual dlsym(3)
NAME
dlsym - 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().
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 diagnostic information is available through dlerror().
ERRORS
No errors are defined.
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);
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 invocation 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 flag) - or an
object that was included in the same dlopen() operation that loaded this one. The RTLD_NEXT flag 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 malloc() that embedded some statistics gathering about memory allocations, such an implementation could use the real malloc() definition
to perform the memory allocation - and itself only embed the necessary logic to implement the statistics gathering function.
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 resolution 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.
RELATED INFORMATION
dlclose(3), dlerror(3), dlopen(3). delim off
dlsym(3)