HP-UX Reference (11i v1 00/12) - 3 Library Functions A-M (vol 6)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/!!!intro.3c
________________________________________________________________
___ ___
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 is the special flag RTLD_NEXT. 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.
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 infor-
mation will be availablethrough 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");
/* invoke function, passing value of integer as a parameter */
i = (*fptr)(*iptr);
The next example shows how one can use dlsym with RTLD_NEXT to add functionality to an existing inter-
face. Again, error checking has been omitted.
HP-UX Release 11i: December 2000 − 1 − Section 3−−157
___
___