dlsym(3) [ultrix man page]
DLSYM(3) Linux Programmer's Manual DLSYM(3) NAME
dlsym, dlvsym - obtain address of a symbol in a shared object or executable SYNOPSIS
#include <dlfcn.h> void *dlsym(void *handle, const char *symbol); #define _GNU_SOURCE #include <dlfcn.h> void *dlvsym(void *handle, char *symbol, char *version); Link with -ldl. DESCRIPTION
The function dlsym() takes a "handle" of a dynamic loaded shared object returned by dlopen(3) along with a null-terminated symbol name, and returns the address where that symbol is loaded into memory. If the symbol is not found, in the specified object or any of the shared objects that were automatically loaded by dlopen(3) when that object was loaded, dlsym() returns NULL. (The search performed by dlsym() is breadth first through the dependency tree of these shared objects.) Since the value of the symbol could actually be NULL (so that a NULL return from dlsym() need not indicate an error), the correct way to test for an error is to call dlerror(3) to clear any old error conditions, then call dlsym(), and then call dlerror(3) again, saving its return value into a variable, and check whether this saved value is not NULL. There are two special pseudo-handles that may be specified in handle: RTLD_DEFAULT Find the first occurrence of the desired symbol using the default shared object search order. The search will include global sym- bols in the executable and its dependencies, as well as symbols in shared objects that were dynamically loaded with the RTLD_GLOBAL flag. RTLD_NEXT Find the next occurrence of the desired symbol in the search order after the current object. This allows one to provide a wrapper around a function in another shared object, so that, for example, the definition of a function in a preloaded shared object (see LD_PRELOAD in ld.so(8)) can find and invoke the "real" function provided in another shared object (or for that matter, the "next" definition of the function in cases where there are multiple layers of preloading). The _GNU_SOURCE feature test macro must be defined in order to obtain the definitions of RTLD_DEFAULT and RTLD_NEXT from <dlfcn.h>. The function dlvsym() does the same as dlsym() but takes a version string as an additional argument. RETURN VALUE
On success, these functions return the address associated with symbol. On failure, they return NULL; the cause of the error can be diag- nosed using dlerror(3). VERSIONS
dlsym() is present in glibc 2.0 and later. dlvsym() first appeared in glibc 2.1. ATTRIBUTES
For an explanation of the terms used in this section, see attributes(7). +------------------+---------------+---------+ |Interface | Attribute | Value | +------------------+---------------+---------+ |dlsym(), dlvsym() | Thread safety | MT-Safe | +------------------+---------------+---------+ CONFORMING TO
POSIX.1-2001 describes dlsym(). The dlvsym() function is a GNU extension. NOTES
History The dlsym() function is part of the dlopen API, derived from SunOS. That system does not have dlvsym(). EXAMPLE
See dlopen(3). SEE ALSO
dl_iterate_phdr(3), dladdr(3), dlerror(3), dlinfo(3), dlopen(3), ld.so(8) COLOPHON
This page is part of release 4.15 of the Linux man-pages project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/. Linux 2017-09-15 DLSYM(3)
Check Out this Related Man Page
dlsym(3C) dlsym(3C) NAME
dlsym - get the address of a symbol in a shared object or executable SYNOPSIS
#include <dlfcn.h> void *dlsym(void *restrict handle, const char *restrict name); The dlsym() function allows a process to obtain the address of a symbol that is defined within a shared object or executable. The handle argument is either the value returned from a call to dlopen() or one of a family of special handles. The name argument is the symbol's name as a character string. If handle is returned from dlopen(), the associated 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(3C) and . The following special handles are supported. RTLD_DEFAULT Instructs dlsym() to search for the named symbol starting with the first object loaded, typically the dynamic executable. The search continues through the list of initial dependencies that are loaded with the process, followed by any objects obtained with dlopen(3C). This search follows the default model that is used to relocate all objects within the process. This model also provides for transitioning into a lazy loading environment. If a symbol can not be found in the presently loaded objects, any pending lazy loaded objects are processed in an attempt to locate the symbol. This loading compensates for objects that have not fully defined their dependencies. However, this compensation can undermine the advantages of lazy loading. RTLD_PROBE Instructs dlsym() to search for the named symbol in the same manner as occurs with a handle of RTLD_DEFAULT. However, this model only searches for symbols in the presently loaded objects, together with any lazy loadable objects specifically identified by the caller to provide the named symbol. This handle does not trigger an exhaustive load of any lazy loadable symbols in an attempt to find the named symbol. This handle can provide a more optimal search than would occur using RTLD_DEFAULT. RTLD_NEXT Instructs dlsym() to search for the named symbol in the objects that were loaded following the object from which the dlsym() call is being made. RTLD_SELF Instructs dlsym() to search for the named symbol in the objects that were loaded starting with the object from which the dlsym() call is being made. When used with a special handle, dlsym() is selective in searching objects that have been loaded using dlopen(). These objects are searched for symbols if one of the following conditions are true. o The object is part of the same local dlopen() dependency hierarchy as the calling object. See the for a description of dlopen() dependency hierarchies. o The object has global search access. See dlopen(3C) 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. The 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(3C). Example 1: Use dlopen() and dlsym() to access a function or data objects. 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); Example 2: Use dlsym() to verify that a particular function is defined. The following code fragment shows how to use dlsym() to verify that a function is defined. If the function exists, the function is called. 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. These facilities are available to dynamically-linked processes only. See the . 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(3C), dlclose(3C), dldump(3C), dlerror(3C), dlinfo(3C), dlopen(3C), attributes(5), standards(5) If an object is acting as a filter, care should be taken when interpreting the address of any symbol obtained using a handle to this object. For example, using dlsym(3C) to obtain the symbol _end for this object, results in returning the address of the symbol _end within the filtee, not the filter. For more information on filters see the . 26 Sep 2005 dlsym(3C)