HP-UX Reference (11i v2 07/12) - 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);
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
dlo-
pen()
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 infor-
mation 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
HP-UX 11i Version 2: December 2007 Update − 1 − Hewlett-Packard Company 327