dlsym(S)
dlsym --
get the address of a symbol in shared object
Synopsis
#include <dlfcn.h>
void *dlsym(void handle, const char name);
Description
dlsym 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(S)].
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(S)].
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.
Return values
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.
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 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;
}
References
dlclose(S),
dlerror(S),
dlopen(S)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005