dlsym Subroutine

Purpose

Looks up the location of a symbol in a module that is loaded with dlopen.

Syntax

#include <dlfcn.h>

void *dlsym(Handle, Symbol);
void *Handle;
const char *Symbol;

Description

The dlsym subroutine looks up a named symbol exported from a module loaded by a previous call to the dlopen subroutine. Only exported symbols are found by dlsym. See the ld command to see how to export symbols from a module.

Item	Description
Handle	Specifies a value returned by a previous call to dlopen or one of the special handles RTLD_DEFAULT, RTLD_NEXT or RTLD_MYSELF.
Symbol	Specifies the name of a symbol exported from the referenced module in the form of a `NULL`-terminated string or the special symbol name RTLD_ENTRY.

Note: C++ symbol names should be passed to dlsym in mangled form; dlsym does not perform any name demangling on behalf of the calling application.

In case of the special handle RTLD_DEFAULT, dlsym searches for the named symbol starting with the first module loaded. It then proceeds through the list of initial loaded modules and any global modules obtained with dlopen until a match is found. This search follows the default model employed to relocate all modules within the process.

In case of the special handle RTLD_NEXT, dlsym searches for the named symbol in the modules that were loaded following the module from which the dlsym call is being made.

In case of the special handle RTLD_MYSELF, dlsym searches for the named symbol in the modules that were loaded starting with the module from which the dlsym call is being made.

In case of the special symbol name RTLD_ENTRY, dlsym returns the module's entry point. The entry point, if present, is the value of the module's loader section symbol marked as entry point.

In case of RTLD_DEFAULT, RTLD_NEXT, and RTLD_MYSELF, if the modules being searched have been loaded from dlopen calls, dlsym searches the module only if the caller is part of the same dlopen dependency hierarchy, or if the module was given global search access. See dlopen for a discussion of the RTLD_GLOBAL mode.

A search for the named symbol is based upon breadth-first ordering of the module and its dependants. If the module was constructed using the -G or -brtl linker option, the module's dependants will include all modules named on the ld command line, in the original order. The dependants of a module that was not linked with the -G or -brtl linker option will be listed in an unspecified order.

Return Values

If the named symbol is found, its address is returned. If the named symbol is not found, NULL is returned and errno is set to 0. If Handle or Symbol is invalid, NULL is returned and errno is set to EINVAL .

If the first definition found is an export of an imported symbol, this definition will satisfy the search. The address of the imported symbol is returned. If the first definition is a deferred import, the definition is ignored and the search continues.

If the named symbol refers to a BSS symbol (uninitialized data structure), the search continues until an initialized instance of the symbol is found or the module and all of its dependants have been searched. If an initialized instance is found, its address is returned; otherwise, the address of the first uninitialized instance is returned.

Error Codes

Item	Description
EINVAL	If the Handle parameter does not refer to a module opened by dlopen that is still loaded or if the Symbol parameter points to an invalid address, the dlsym subroutine returns `NULL` and errno is set to EINVAL.