man Pages(3): Library Routines

dlsym(3X)

NAME

dlsym- get the address of a symbol in a shared object

SYNOPSIS

cc [ flag ... ] file ... -ldl [ library ... ]
#include <dlfcn.h>

handle

name

DESCRIPTION

dlsym() is one of a family of routines that give the user direct access to the dynamic linking facilities. (See Linker and Libraries Guide ). These routines are made available via the library loaded when the option -ldl is passed to the link-editor.

Note: These routines are available to dynamically-linked processes ONLY.

dlsym() allows a process to obtain the address of a symbol defined within a shared object. handle is either the value returned from a call to dlopen() or one of the special flags RTLD_NEXT or RTLD_DEFAULT. name is the symbol's name as a character string.

In the case of a handle returned from dlopen() the corresponding shared object must not have been closed using dlclose(). dlsym() will search for the named symbol in all shared objects loaded automatically as a result of loading the object referenced by handle. See dlopen(3X).

In the case of the special handle RLTD_NEXT, dlsym() will search for the named symbol in the objects that were loaded following the object from which the dlsym() call is being made.

In the case of the special handle RTLD_DEFAULT, dlsym() will search for the named symbol, starting with the first object loaded and proceeding through the list of loaded objects until a match is found. This search follows the default model employed to relocate all objects within the process.

In the case of both RLTD_NEXT and RTLD_DEFAULT, if the objects being searched have been loaded from dlopen() calls, dlsym() will search the object only if the caller is part of the same dlopen() dependency hierarchy, or if the object was given global search access. See dlopen(3X) for a discussion of the RTLD_GLOBAL mode.

RETURN VALUES

If handle does not refer to a valid object opened by dlopen(), is not the special flag RTLD_NEXT, or if the named symbol cannot be found within any of the objects associated with handle, dlsym() will return NULL. More detailed diagnostic information is available through dlerror().

EXAMPLES

Example 1 The use of `dlopen()` and `dlsym()`.

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        *iptr, (*fptr)(int);

/* open the needed object */
handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_LAZY);

/* find the address of function and data objects */
fptr = (int (*)(int))dlsym(handle, "my_function");
iptr = (int *)dlsym(handle, "my_object");

/* invoke function, passing value of integer as a parameter */
(*fptr)(*iptr);

The following code fragment shows how dlsym() can be used to check to see that a particular function is defined and to call it only if it is.

int         (*fptr)();

if ((fptr = (int (*)())dlsym(RTLD_DEFAULT,
    "my_function")) != NULL) {
        (*fptr)();
}

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe