Dynamic Linking Library Functions                      dlsym(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  sym-
     bol  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  dlo-
     pen(), is not the special handle RTLD_DEFAULT, RTLD_NEXT, or
     RTLD_SELF, or if the named symbol cannot be found within any

SunOS 5.8           Last change: 13 Mar 2000                    1

Dynamic Linking Library Functions                      dlsym(3DL)

     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 sim-
     plicity, 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  func-
     tion 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 facili-
     ties (see Linker and Libraries Guide) and are  available  to
     dynamically-linked processes only.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

SunOS 5.8           Last change: 13 Mar 2000                    2

Dynamic Linking Library Functions                      dlsym(3DL)

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

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

     Linker and Libraries Guide

SunOS 5.8           Last change: 13 Mar 2000                    3