The dlsym subroutine includes information for dlsym subroutine on a POWER-based platform and on dlsym subroutine on an Itanium-based platform.
dlsym Subroutine on POWER-based Platform
Looks up the location of a symbol in a module that is loaded with dlsym.
#include <dlfcn.h>
void *dlsym(Data, Symbol); void *Data; const char *Symbol;
The dlsym
subroutine looks up a named symbol exported from a module loaded by a previous
call to the dlopen subroutine. Only exported symbols are
found by dlsym. See the ld
command to see how to export symbols from a module.
| Data | Specifies a value returned by a previous call to dlopen. |
| Symbol | Specifies the name of a symbol exported from the referenced module. The form should be a NULL-terminated string. |
Note: C++ symbol names should be passed to dlsym in mangled form; dlsym does not perform any name demangling on behalf of the calling application.
A search for the named symbol is based upon breadth-first ordering of the module and its dependants. If the module was constructed using the -G or -brtl linker option, the module's dependants will include all modules named on the ld command line, in the original order. The dependants of a module that was not linked with the -G or -brtl linker option will be listed in an unspecified order.
If the named symbol is found, its address is returned. If the named symbol is not found, NULL is returned and errno is set to 0. If Data or Symbol are invalid, NULL is returned and errno is set to EINVAL .
If the first definition found is an export of an imported symbol, this definition will satisfy the search. The address of the imported symbol is returned. If the first definition is a deferred import, the definition is ignored and the search continues.
If the named symbol refers to a BSS symbol (uninitialized data structure), the search continues until an initialized instance of the symbol is found or the module and all of its dependants have been searched . If an initialized instance is found, its address is returned; otherwise, the address of the first uninitialized instance is returned.
This subroutine is part of Base Operating System (BOS) Runtime.
The dlclose (dlclose Subroutine) subroutine, dlerror (dlerror Subroutine) subroutine, dlopen (dlopen Subroutine) subroutine, load (load Subroutine) subroutine, loadbind (loadbind Subroutine) subroutine, loadquery (loadquery Subroutine)subroutine, unload subroutine.
The ld command.
dlsym Subroutine on Itanium-based Platform
Gets the address of a symbol in shared object.
#include <dlfcn.h> void *dlsym(void *handle, const char *name);
The dlsym subroutine allows a process to obtain the address of a symbol defined within a shared object previously opened by dlopen. handle is 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 (dlopen Subroutine)]. The symbol resolution algorithm used is described in dlopen.
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 (dlopen Subroutine)]. 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.
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.
If handle does not refer to a valid object opened by dlopen or is not the special value RTLD_NEXT, or if the named symbol cannot be found within any of the objects associated with handle, dlsym returns NULL. More detailed diagnostic information is available through dlerror.
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 interface. Again, error checking has been omitted.
extern void record_malloc(void *, size_t);
void *
malloc(size_t sz)
{
void *ptr;
void *(*real_malloc)(size_t);
real_malloc = (void * (*)(size_t))dlsym(RTLD_NEXT, "malloc");
ptr = (*real_malloc)(sz);
record_malloc(ptr, sz);
return ptr;
}
The dladdr (dladdr Subroutine) subroutine, dlclose (dlclose Subroutine) subroutine, dlerror (dlerror Subroutine) subroutine, and dlopen (dlopen Subroutine) subroutine.