HP-UX Linker and Libraries User's Guide

Table 25 Parameters
DefinitionParameter
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 library must
not have been closed using dlclose.
handle
The symbol's name as a character string.name
Return Values
If handle does not refer to a valid shared library opened by dlopen, or if the named symbol
cannot be found within any of the shared libraries associated with handle, dlsym returns NULL.
The dlerror routine provides more detailed diagnostic information.
Description
The dlsym routine allows a process to obtain the address of a symbol defined within a shared
library previously opened by dlopen.
The dlsym routine searches for the named symbol in all shared libraries loaded automatically as
a result of loading the shared library referenced by handle [see dlopen(3C)].
If handle is RTLD_NEXT, the search begins with the “"next"” shared library after the shared library
from which dlsym was invoked. Shared libraries are searched using a load order symbol resolution
algorithm [see dlopen(3C)]. The "next" shared library, and all other shared libraries 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 shared libraries 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, it searches symbols in objects that
were loaded in the same dlopen invocation as the caller object.
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 gathers the necessary information, and use dlsym with
RTLD_NEXT to find the “"real"” malloc, which performs the actual memory allocation. Of course,
this “"real" ”malloc can be another user-defined interface that added its own value and then
used RTLD_NEXT to find the system malloc.
Using dlopen and dlsym to access either function or data objects
The following example shows how to 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);
158 Shared Library Management Routines