# dlsym

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           dlsym — get the address of a symbol from a symbol table handle
    


## SYNOPSIS



           #include <dlfcn.h>
    
           void *dlsym(void *restrict _handle_ , const char *restrict _name_);
    


## DESCRIPTION



           The _dlsym_() function shall obtain the address of a symbol (a
           function identifier or a data object identifier) defined in the
           symbol table identified by the _handle_ argument. The _handle_
           argument is a symbol table handle returned from a call to _dlopen_()
           (and which has not since been released by a call to _dlclose_()),
           and _name_ is the symbol's name as a character string. The return
           value from _dlsym_(), cast to a pointer to the type of the named
           symbol, can be used to call (in the case of a function) or access
           the contents of (in the case of a data object) the named symbol.
    
           The _dlsym_() function shall search for the named symbol in the
           symbol table referenced by _handle_.  If the symbol table was
           created with lazy loading (see RTLD_LAZY in _dlopen_()), load
           ordering shall be used in _dlsym_() operations to relocate
           executable object files needed to resolve the symbol. The symbol
           resolution algorithm used shall be dependency order as described
           in _dlopen_().
    
           The RTLD_DEFAULT and RTLD_NEXT symbolic constants (which may be
           defined in _< dlfcn.h>_) are reserved for future use as special
           values that applications may be allowed to use for _handle_.
    


## RETURN VALUE



           Upon successful completion, if _name_ names a function identifier,
           _dlsym_() shall return the address of the function converted from
           type pointer to function to type pointer to **void** ; otherwise,
           _dlsym_() shall return the address of the data object associated
           with the data object identifier named by _name_ converted from a
           pointer to the type of the data object to a pointer to **void**.  If
           _handle_ does not refer to a valid symbol table handle or if the
           symbol named by _name_ cannot be found in the symbol table
           associated with _handle_ , _dlsym_() shall return a null pointer.
    
           More detailed diagnostic information shall be available through
           _dlerror_().
    


## ERRORS



           No errors are defined.
    
           _The following sections are informative._
    


## EXAMPLES



           The following example shows how _dlopen_() and _dlsym_() can be used
           to access either a function or a data object. For simplicity,
           error checking has been omitted.
    
               void *handle;
               int (*fptr)(int), *iptr, result;
               /* open the needed symbol table */
               handle = dlopen("/usr/home/me/libfoo.so", RTLD_LOCAL | RTLD_LAZY);
               /* find the address of the function my_function */
               fptr = (int (*)(int))dlsym(handle, "my_function");
               /* find the address of the data object my_object */
               iptr = (int *)dlsym(handle, "my_OBJ");
               /* invoke my_function, passing the value of my_OBJ as the parameter */
               result = (*fptr)(*iptr);
    


## APPLICATION USAGE



           The following special purpose values for _handle_ are reserved for
           future use and have the indicated meanings:
    
           RTLD_DEFAULT
                       The identifier lookup happens in the normal global
                       scope; that is, a search for an identifier using
                       _handle_ would find the same definition as a direct use
                       of this identifier in the program code.
    
           RTLD_NEXT   Specifies the next executable object file after this
                       one that defines _name_.  This one refers to the
                       executable object file containing the invocation of
                       _dlsym_().  The next executable object file is the one
                       found upon the application of a load order symbol
                       resolution algorithm (see _dlopen_()).  The next symbol
                       is either one of global scope (because it was
                       introduced as part of the original process image or
                       because it was added with a _dlopen_() operation
                       including the RTLD_GLOBAL flag), or is in an
                       executable object file that was included in the same
                       _dlopen_() operation that loaded this one.
    
           The RTLD_NEXT flag is useful to navigate an intentionally created
           hierarchy of multiply-defined symbols created through
           interposition. For example, if a program wished to create an
           implementation of _malloc_() that embedded some statistics gathering
           about memory allocations, such an implementation could use the
           real _malloc_() definition to perform the memory allocation — and
           itself only embed the necessary logic to implement the statistics
           gathering function.
    
           Note that conversion from a **void *** pointer to a function pointer
           as in:
    
               fptr = (int (*)(int))dlsym(handle, "my_function");
    
           is not defined by the ISO C standard. This standard requires this
           conversion to work correctly on conforming implementations.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *