NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

       #include <dlfcn.h>

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

PARAMETERS    [Toc]    [Back]

       The value returned from a call to dlopen() (and which  has
       not since been released by a call to dlclose()).  The name
       (character string) of the symbol being sought.

DESCRIPTION    [Toc]    [Back]

       The dlsym()  function  allows  a  process  to  obtain  the
       address of a symbol defined within an object made accessible
 by a dlopen() call.

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

NOTES    [Toc]    [Back]

       Use  of the dlsym() routine is the preferred mechanism for
       retrieving  symbol  addresses.   This   routine   reliably
       returns  the  current  address of a symbol at any point in
       the program, while the dynamic symbol resolution described
       previously  might not function as expected due to compiler
       optimizations.  For example, the address of a symbol might
       be  saved  in a register prior to a dlopen() call, and the
       saved address might then be used after the  dlopen()  call
       -- even if the dlopen() call changed the resolution of the
       symbol.

ERRORS    [Toc]    [Back]

       No errors are defined.

RETURN VALUE    [Toc]    [Back]

       The dlsym() function will return NULL 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. More detailed diagnostic information is
       available through dlerror().

APPLICATION USAGE    [Toc]    [Back]

       Special-purpose values for handle are reserved for  future
       use.  These  values  and their meanings are: 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(3)).
       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  option -- or an object that was included
       in the same dlopen() operation that loaded this  one.  The
       RTLD_NEXT  option  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.

EXAMPLES    [Toc]    [Back]

       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);

SEE ALSO    [Toc]    [Back]

       dlclose(3), dlerror(3), dlopen(3).



                                                         dlsym(3)