Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
Dynamic Linking Library Functionsdlsym(3DL)


NAME

 dlsym - get the address of a symbol in a shared object or executable

SYNOPSIS

 
cc [ flag ... ] file ... -ldl [ library ... ]
#include <dlfcn.h>
void *dlsym(void *handle, const char *name);

DESCRIPTION

 

The dlsym() function allows a process to obtain the address of a symbol defined within a shared object or executable. The handle argument is either the value returned from a call to dlopen() or one of the special handles RTLD_DEFAULT, RTLD_NEXT, or RTLD_SELF. The name argument is the symbol's name as a character string.

In the case of a handle returned from dlopen(), the corresponding shared object must not have been closed using dlclose(). The dlsym() function searches for the named symbol in all shared objects loaded automatically as a result of loading the object referenced by handle. See dlopen(3DL).

In the case of the special handle RTLD_DEFAULT, dlsym() searches for the named symbol starting with the first object loaded and proceeding through the list of initial loaded objects, and any global objects obtained with dlopen(3DL), until a match is found. This search follows the default model employed to relocate all objects within the process.

In the case of the special handle 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.

In the case of the special handle RTLD_SELF, dlsym() searches for the named symbol in the objects that were loaded starting with the object from which the dlsym() call is being made.

In the case of RTLD_DEFAULT, RTLD_NEXT, and RTLD_SELF, if the objects being searched have been loaded from dlopen() calls, 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(3DL) for a discussion of the RTLD_GLOBAL mode.

RETURN VALUES

 

If handle does not refer to a valid object opened by dlopen(), is not the special handle RTLD_DEFAULT, RTLD_NEXT, or RTLD_SELF, or if the named symbol cannot be found within any of the objects associated with handle, dlsym() will return NULL. More detailed diagnostic information is available through dlerror(3DL).

EXAMPLES

 Example 1. Using dlopen and dlsym to access a function or data objects.
 

The following example shows how one can 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. Using dlsym to verify that a particular function is defined.
 

The following code fragment shows how dlsym() can be used to verify that a particular function is defined and to call it only if it is.

 
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 facilities (see Linker and Libraries Guide) and are available to dynamically-linked processes only.

ATTRIBUTES

 

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE
MT-LevelMT-Safe

SEE ALSO

 

ld(1), dladdr(3DL), dlclose(3DL), dldump(3DL), dlerror(3DL), dlopen(3DL), attributes(5)

Linker and Libraries Guide


SunOS 5.9Go To TopLast Changed 13 Mar 2000

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.