dlsym() — Obtain the address of a symbol from a dlopen() object

Standards

Standards / Extensions	C or C++	Dependencies
Single UNIX Specification, Version 3	both	z/OS® V1R6

Format

#define _UNIX03_SOURCE
#include <dlfcn.h>

void  *dlsym(void *__restrict__ handle, const char *__restrict__ name);

General description

Obtains the address of a symbol defined within a dynamic link library (DLL) made accessible through a dlopen() call. The handle argument is the value returned from a call to dlopen() (which has not been released by a call to dlclose()), and name is the symbol's name as a character string.

The DLL that was loaded by dlopen() will be searched for the named symbol. If the symbol is not found in that DLL, then the dependent DLLs of that DLL will be searched, followed by any dependents of those, and continuing in a breadth-first manner until the named symbol is found or all dependent DLLs have been searched. This search order determines how duplicate symbols in different DLLs will be found, although the order in which dependent DLLs at the same level are searched is indeterminate.

Also note that a search of dependent DLLs by dlsym() will not result in unloaded dependent DLLs being loaded. Only the dependent DLLs loaded as part of the call to dlopen() will be searched. If the full set of dependent DLLs need to be available to subsequent calls to dlsym(), make sure the DLL is opened with the RTLD_NOW load flag. It is indeterminate which dependent DLLs are loaded when RTLD_LAZY is specified

The only exception to this is the global symbol object obtained via a dlopen(NULL,0) call, in which case all DLLs (excluding those opened with RTLD_LOCAL) are searched in the order in which they were loaded.

Returned value

NULL is returned:

If handle does not refer to a valid DLL opened by dlopen(),
or the named symbol (name) cannot be found within any of the DLLs associated with handle.

Usage notes

The named symbol can be either an exported data item or function.
DLLs are enclave level resources. See z/OS XL C/C++ Programming Guide for more information about the use of DLLs in a multi-threaded environment.
C++ symbol names should be passed to dlsym() in mangled form; dlsym() does not perform any name mangling on behalf of the calling application.
More detailed diagnostic information is available through dlerror(), the _EDC_DLL_DIAG environment variable, and the Language Environment® DLL Failure control block (CEEDLLF) chain.
This function is not available under SPC, MTF and CSP environments.

Example

The following example shows how dlopen() and dlsym() can be used 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", RTLD_LOCAL | 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);