NAME

       dlsym - obtain the address of a symbol from a dlopen object

SYNOPSIS

       #include <dlfcn.h>

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

DESCRIPTION

       The  dlsym()  function  shall obtain the address of a symbol defined within an object made
       accessible through a dlopen() call. The handle argument is the value returned from a  call
       to  dlopen()  (and which has not since been released via a call to dlclose()), and name is
       the symbol's name as a character string.

       The dlsym() function shall search for the named symbol in all objects loaded automatically
       as  a  result of loading the object referenced by handle (see dlopen() ). Load ordering is
       used in dlsym() operations upon the global symbol object. The symbol resolution  algorithm
       used shall be dependency order as described in dlopen() .

       The RTLD_DEFAULT and RTLD_NEXT flags are reserved for future use.

RETURN VALUE

       If  handle  does  not  refer  to a valid object opened by dlopen(), or if the named symbol
       cannot be found within any of the objects associated with  handle,  dlsym()  shall  return
       NULL. 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 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", RTLD_LOCAL | RTLD_LAZY);

              /* find the address of function and data objects */
              *(void **)(&fptr) = dlsym(handle, "my_function");
              iptr = (int *)dlsym(handle, "my_object");

              /* invoke function, passing value of integer as a parameter */
              (*fptr)(*iptr);

APPLICATION USAGE

       Special purpose values for handle are reserved for future use.   These  values  and  their
       meanings are:

       RTLD_DEFAULT
              The  symbol  lookup  happens  in  the  normal global scope; that is, a search for a
              symbol using this handle would find the same definition as a  direct  use  of  this
              symbol in the program code.

       RTLD_NEXT
              Specifies the next object after this one that defines name.  This one refers to the
              object containing the invocation of dlsym(). The next object is the one found  upon
              the  application  of  a load order symbol resolution algorithm (see dlopen() ). The
              next object 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 an object 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.

RATIONALE

       The ISO C standard does not require that pointers to functions can be cast back and  forth
       to  pointers  to  data. Indeed, the ISO C standard does not require that an object of type
       void * can hold a pointer to a function. Implementations  supporting  the  XSI  extension,
       however,  do  require  that an object of type void * can hold a pointer to a function. The
       result of converting a pointer to a function into a pointer to another data  type  (except
       void  *) is still undefined, however. Note that compilers conforming to the ISO C standard
       are required to generate a warning if a conversion from a void *  pointer  to  a  function
       pointer is attempted as in:

              fptr = (int (*)(int))dlsym(handle, "my_function");

       Due  to  the  problem noted here, a future version may either add a new function to return
       function pointers, or the current  interface  may  be  deprecated  in  favor  of  two  new
       functions: one that returns data pointers and the other that returns function pointers.

FUTURE DIRECTIONS

       None.

SEE ALSO

       dlclose()  ,  dlerror()  , dlopen() , the Base Definitions volume of IEEE Std 1003.1-2001,
       <dlfcn.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .