DLSYM(3P)                  POSIX Programmer's Manual                 DLSYM(3P)



PROLOG
       This  manual page is part of the POSIX Programmer's Man-
       ual.  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  -  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 sym-
       bol 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 sym-
       bol's name as a character string.

       The dlsym() function shall search for the  named  symbol
       in all objects loaded automatically as a result of load-
       ing 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 con-
              taining  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 intention-
       ally created hierarchy of multiply-defined symbols  cre-
       ated  through  interposition.  For example, if a program
       wished to create  an  implementation  of  malloc()  that
       embedded  some statistics gathering about memory alloca-
       tions, such an implementation could use  the  real  mal-
       loc()  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  func-
       tion. Implementations supporting the XSI extension, how-
       ever, 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  Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute  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.open-
       group.org/unix/online.html .



IEEE/The Open Group                  2003                            DLSYM(3P)
