dlsym()

Get the address of a symbol in a shared object

Synopsis:

#include <dlfcn.h>

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

Library:

libc

Description:

The dlsym() function lets a process obtain the address of the symbol specified by name defined in a shared object. handle is either the value returned from a call to dlopen(), or the special flag RTLD_DEFAULT.

The dlsym() function is available only to dynamically linked processes.

If handle is a handle returned by dlopen(), that shared object must not have been closed with dlclose(). The dlsym() functions also searches for the named symbol in the objects loaded as part of the dependencies for that object.

If handle is RTLD_DEFAULT, dlsym() searches all objects in the current process, in load-order.

In the case of RTLD_DEFAULT, if the objects being searched were loaded with dlopen(), dlsym() searches the object only if the caller is part of the same dependency hierarchy, or if the object was loaded with global search access (using the RTLD_GLOBAL mode).

Returns:

A pointer to the named symbol for success, or NULL if an error occurs.

Errors:

If an error occurs, more detailed diagnostic information is available from dlerror().

Examples:

Use dlsym() to find a function pointer and a pointer to a global variable in a shared library:

typedef int (*foofunc)( int );

void* handle;
int* some_global_int;
foofunc brain;

/* Open a shared library. */
handle = dlopen( "/usr/nto/x86/lib/libfoo.so.1", RTLD_NOW );

/* Find the address of a function and a global integer. */
brain = (foofunc)dlsym( handle, "takeover_world" );
some_global_int = (int* )dlsym( handle, "my_global_int" );

/* Invoke the function and print the int. */
x = (*brain)( 5 );
printf( "that global is %d\n", some_global_int );

Check to see if a function is defined, and call it if it is:

typedef int (*funcptr)( void );

funcptr funk = NULL;

funk = (funcptr)dlsym( RTLD_DEFAULT, "get_funky" );
if( funk != NULL ) {
    (*funk)();
}

Classification:

Standard Unix

Caveats:

Function pointers are a pain; use typedefs to help preserve your sanity.

See also:

dladdr(), dlclose(), dlerror(), dlopen()