NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUES | EXAMPLES | ATTRIBUTES | SEE ALSO
#include <cx/dlfcn.h>void *dlsym(void *handle, const char *name);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
DYNAMIC_LIB
dlsym() is a member of the dynamic linking API, a family of routines that give the user direct access to dynamic linking functionality.
dlsym() is only available to programs and libraries compiled with imake rules of the form DynamicTypeTarget(), where Type is one of User, Sup, CXXUser, CXXSup or Library.
See the ChorusOS 5.0 Application Developer's Guide for more information on building executables with dynamic libraries.
dlsym() allows an actor to obtain the address of a symbol defined within a dynamic object. The handle is either the value returned from a call to dlopen() or one of the special flags RTLD_NEXT or RTLD_DEFAULT. The name is the symbol's name as a character string.
If the handle used has been returned by dlopen(), the corresponding dynamic object must not have been closed using dlclose(). dlsym() searches for the named symbol in all dynamic objects loaded automatically as a result of loading the object referenced by handle. For details, see dlopen(2K).
If the handle used is RTLD_NEXT, dlsym() searches for the named symbol in the objects that were loaded following the object from which the dlsym() call is being made.
If the handle used is RTLD_DEFAULT, dlsym() searches for the named symbol, starting with the first object loaded and proceeding through the list of loaded objects until a match is found. This search follows the default model employed to relocate all objects within the actor.
If the handle used is either RTLD_NEXT or RTLD_DEFAULT and if the objects being searched have been loaded using dlopen(), dlsym() searches the object only if the caller is part of the same dlopen() dependency hierarchy, or if the object was given global search access. See dlopen(2K) for a discussion of the RTLD_GLOBAL mode.
If the specified handle does not refer to a valid object opened using dlopen(), is not the special flag RTLD_NEXT, or if the named symbol cannot be found within any of the objects associated with handle, then dlsym() returns NULL. More detailed diagnostic information is available through dlerror().
The following example shows 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 object needed */ handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_NOW); /* 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);
The following example shows how to use dlsym() to check that a particular function is defined and to call it only if it is defined.
int (*fptr)(); if ((fptr = (int (*)())dlsym(RTLD_DEFAULT, "my_function")) != NULL) { (*ftpr)(); }
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUES | EXAMPLES | ATTRIBUTES | SEE ALSO