Standard C Library Functions dlsym(3C)
NAME
dlsym - get the address of a symbol in a shared object or
executableSYNOPSIS
#include
void *dlsym(void *restrict handle, const char *restrict name);
DESCRIPTION
The dlsym() function allows a process to obtain the address
of a symbol that is defined within a shared object or exe-
cutable. The handle argument is either the value returnedfrom a call to dlopen() or one of a family of special han-
dles. 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 handlecan 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. Withoutthis mode, the dlsym() function searches for the named sym-
bol in the group of shared objects loaded automatically as a result of loading the object referenced by handle. See dlopen(3C) and NOTES. 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 objectsobtained with dlopen(3C). This search fol-
lows the default model that is used to relo-
cate 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 areprocessed in an attempt to locate the sym-
bol. This loading compensates for objectsthat have not fully defined their dependen-
cies. However, this compensation can under-
mine the advantages of lazy loading.SunOS 5.11 Last change: 17 May 2010 1
Standard C Library Functions dlsym(3C)
RTLD_PROBE Instructs dlsym() to search for the named
symbol in the same manner as occurs with ahandle of RTLD_DEFAULT. However, RTLD_PROBE
only searches for symbol definitions in the presently loaded objects, together with anylazy loadable objects specifically identi-
fied by the caller to provide the named sym-
bol. This handle does not trigger an exhaus-
tive load of any lazy loadable symbols in anattempt to find the named symbol. This han-
dle can provide a more optimal search thanwould occur using RTLD_DEFAULT.
RTLD_NEXT Instructs dlsym() to search for the named
symbol in the objects that were loaded fol-
lowing 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 thedlsym() 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 follow-
ing conditions are true. o The object is part of the same local dlopen() dependency hierarchy as the calling object. See the Linker and Libraries Guide 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.
RETURN VALUES
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).EXAMPLES
Example 1 Use dlopen() and dlsym() to access a function or
data objects.SunOS 5.11 Last change: 17 May 2010 2
Standard C Library Functions dlsym(3C)
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 ver-
ify 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)(); }USAGE
The dlsym() function is one of a family of functions that
give the user direct access to the dynamic linking facili-
ties. These facilities are available to dynamically-linked
processes only. See the Linker and Libraries Guide.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 17 May 2010 3
Standard C Library Functions dlsym(3C)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
| Standard | See standards(5). ||_____________________________|_____________________________|
SEE ALSO
ld(1), ld.so.1(1), dladdr(3C), dlclose(3C), dldump(3C),dlerror(3C), dlinfo(3C), dlopen(3C), attributes(5), stan-
dards(5) Linker and Libraries Guide NOTES If an object is acting as a filter, care should be taken when interpreting the address of any symbol obtained using ahandle 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 Linker and Libraries Guide.SunOS 5.11 Last change: 17 May 2010 4