dlsym.3c (2010 09)
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);
Multithread Usage
This routine is thread-safe.
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 does not search symbols in objects that were not loaded in same
dlopen invocation as the
caller object.
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() returns NULL. More detailed diagnostic
information is available through dlerror().
ERRORS
If
dlsym() fails, a subsequent call to dlerrno() returns one of the following values:
[RTLD_ERR_CANT_APPLY_RELOC] Cannot apply relocation in library.
[RTLD_ERR_INTERNAL_ERROR] Internal error encountered in
dlsym().
[RTLD_ERR_INV_HANDLE] Invalid handle.
[RTLD_ERR_INV_NEXT_HANDLE] End of liblist , invalid
RTLD_NEXT argument.
[RTLD_ERR_NO_MEMORY] Out of memory.
[RTLD_ERR_SETCANCELSTATE_FAILED]
__thread_setcancelstate
failed on entry to or
exit from
dlsym().
[RTLD_ERR_SIGENABLE_FAILED]
sigenable failed on exit from dlsym().
[RTLD_ERR_SIGINHIBIT_FAILED]
siginhibit failed on entry to dlsym().
[RTLD_ERR_UNKNOWN_SYMBOL] Unknown symbol.
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 mal-
loc() 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,
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1