NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | USAGE | ATTRIBUTES | SEE ALSO
cc [ flag ... ] file ... -ldl [ library ... ] #include <dlfcn.h>void *dlsym(void *handle, const char *name);
The dlsym() function allows a process to obtain the address of a symbol defined within a shared object or executable. The handle argument is either the value returned from a call to dlopen() or one of the special handles RTLD_DEFAULT, RTLD_NEXT, or RTLD_SELF. The name argument is the symbol's name as a character string.
If handle is returned from dlopen(), the corresponding shared object must not have been closed using dlclose(). A handle can be obtained from dlopen() using the RTLD_FIRST mode. With this mode, the dlsym() function searches for the named symbol in the initial object referenced by handle. Without this mode, the dlsym() function searches for the named symbol in the group of shared objects loaded automatically as a result of loading the object referenced by handle. See dlopen(3DL).
If handle is RTLD_DEFAULT, dlsym() searches for the named symbol starting with the first object loaded and proceeding through the list of initial loaded objects and any global objects obtained with dlopen(3DL) until a match is found. This search follows the default model employed to relocate all objects within the process.
If handle is RTLD_NEXT, dlsym() searches for the named symbol in the objects that were loaded following the object from which the dlsym() call is being made.
If handle RTLD_SELF, dlsym() searches for the named symbol in the objects that were loaded starting with the object from which the dlsym() call is being made.
In the case of RTLD_DEFAULT, RTLD_NEXT, and RTLD_SELF, if the objects being searched have been loaded from dlopen() calls, dlsym() searches 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(3DL) for a discussion of the RTLD_GLOBAL mode.
The dlsym() function returns NULL if handle does not refer to a valid object opened by dlopen() or is not one of the special handles RTLD_DEFAULT, RTLD_NEXT, or RTLD_SELF. The dlsym() function also returns NULL if the named symbol cannot be found within any of the objects associated with handle. Additional diagnostic information is available through dlerror(3DL).
The following code fragment demonstrates how to 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 to use dlsym() to verify that a function is defined. The function is called if it exists.
int (*fptr)(); if ((fptr = (int (*)())dlsym(RTLD_DEFAULT, "my_function")) != NULL) { (*fptr)(); }
The dlsym() function is one of a family of functions that give the user direct access to the dynamic linking facilities. This family of functions is only available to dynamically-linked processes. See the Linker and Libraries Guide.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Standard |
MT-Level | MT-Safe |
ld(1), ld.so.1(1), dladdr(3DL), dlclose(3DL), dldump(3DL), dlerror(3DL), dlinfo(3DL), dlopen(3DL), attributes(5), standards(5)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | USAGE | ATTRIBUTES | SEE ALSO