HP-UX Reference (11i v2 04/09) - 3 Library Functions A-M (vol 6)

d
dlsym(3C) dlsym(3C)
NAME
dlsym - get the address of a symbol in shared library
SYNOPSIS
cc [flag ... ] file ...
-ldl [library] ...
#include <dlfcn.h>
void *dlsym(void *handle, const char *name);
DESCRIPTION
dlsym is one of a family of routines that give the user direct access to the dynamic linking facilities
(using the -ldl option on the compiler or
ld command line). dlsym allows a process to obtain the
address of a symbol defined within a shared object previously opened by
dlopen. handle is a either the
value returned by a call to
dlopen or one of the special flags
RTLD_NEXT, RTLD_SELF, and
RTLD_DEFAULT. In the former case, the corresponding shared object must not have been closed using
dlclose. name is the symbol’s name as a character string.
dlsym searches for the named symbol in all shared objects loaded automatically as a result of loading
the object referenced by handle (see dlopen(3C)).
If handle is
RTLD_NEXT, the search begins with the ‘‘next’’ object after the object from which
dlsym was
invoked. Objects are searched using a load order symbol resolution algorithm (see dlopen (3C)). The
‘‘next’’ object, and all other objects searched, are either of global scope (because they were loaded at
startup or as part of a
dlopen operation with the RTLD_GLOBAL flag) or are objects loaded by the same
dlopen operation that loaded the caller of dlsym.
If handle is
RTLD_SELF, the search begins with the object from which dlsym was invoked. Objects are
searched using the load order symbol resolution algorithm.
If handle is
RTLD_DEFAULT, then the symbol search is done in the scope of the object that invoked
dlsym. For example, if the caller object was loaded as a result of dlopen
with RTLD_GROUP (see
dlopen(3C)), it will not search symbols in objects that were not loaded in same
dlopen invocation as the
caller object.
MULTITHREAD USAGE
This routine is thread-safe.
RETURN VALUE
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, dlsym will return NULL. More detailed diagnostic
information will be available through dlerror.
APPLICATION USAGE
RTLD_NEXT can be used 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 define
its own malloc which would gather the necessary information, and use dlsym with RTLD_NEXT to find
the ‘‘real’’ malloc, which would perform the actual memory allocation. Of course, this ‘‘real’’ malloc
could be another user-defined interface that added its own value and then used RTLD_NEXT to find the
system malloc.
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 i, *iptr;
int (*fptr)(int);
/* open the needed object */
handle = dlopen("/usr/mydir/mylib.so", RTLD_LAZY);
/* find address of function and data objects */
fptr = (int (*)(int))dlsym(handle, "some_function");
iptr = (int *)dlsym(handle, "int_object");
HP-UX 11i Version 2: September 2004 − 1 − Hewlett-Packard Company Section 3−−223