DLSYM(3C)DLSYM(3C)


NAME
     dlsym - Gets the address of a symbol in shared object

SYNOPSIS
     cc [options ...] file ... -lc [library ...]

     #include <dlfcn.h>

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

DESCRIPTION
     dlsym obtains the address of a symbol defined within a shared object
     previously opened by dlopen, sgidlopen_version, or sgidladd.  It
     accepts the following arguments:

     handle    The value returned by a call to dlopen(3C).  dlclose(3C)
               must not have been used to close the corresponding shared
               object.

     name      The symbol's name as a character string.  dlsym  searches
               for the named symbol in all shared objects loaded
               automatically as a result of loading the object referenced
               by handle.  For more information, see dlopen(3C).

               The named object is searched and then the library list of
               the DSO opened on handle is searched (in a pre-order,
               breadth-first search of all listed DSOs).  The first visible
               symbol with the requested name (weak or strong) is returned.

     For information on how names are generally resolved, as distinct from
     dlsym resolution, and on symbol visibility see the NAMESPACE ISSUES
     section of the dlopen(3C) man page.

     For names on the handle returned by dlopen((char *)0,flags), the name
     resolution is in rld(5)-list order according to the internal list
     maintained at run time by rld(5).  For other handles, name resolution
     is in breadth-first order based on following the library-list
     (liblist) of the DSO named in the dlopen(name,flags) call.  Normally,
     these searches result in the same sequence of DSOs being searched, but
     the former searches file a.out and all globally visble DSOs.  The
     latter, however, searches only DSOs in the transitive closure of the
     library-list of the named DSO.

RETURN VALUES
     When casting the return type of dlsym to be a function pointer, the C
     or C++ compiler might emit the following warning:

      warning(1048): cast between pointer-to-object and pointer-to-function

     While a cast from pointer-to-data to pointer-to-function is not
     necessarily portable to all systems, which is what the warning means,
     the cast and the resulting call perform correctly on any system that
     supports dlsym.  When getting function addresses, one could define a
     function such as the one in the following example and call it instead
     of dlsym:

          int (*dlsymfunc(void *handle,char *name))();
          int (*dlsymfunc(void *handle,char *name))()
          {
                  return (int (*)())dlsym(handle,name);
          }

     This would have the effect of moving the warning message to a single
     spot in the program (the dlsymfunc definition) so that the rest of the
     code does not generate this warning.

     If handle does not refer to a valid object opened by dlopen(3C), or if
     the named symbol cannot be found within any of the objects associated
     with handle, dlsym returns NULL.  More detailed diagnostic information
     is available through dlerror(3C).

EXAMPLES
     The following example shows how one can use dlopen(3C) and dlsym to
     access either function or data objects.  For simplicity, error
     checking has been omitted.

          void *handle;
          int i, *iptr;
          int (*fptr)(int);

          /* open the needed object */
          handle = dlopen("/usr/mydir/libx.so", RTLD_LAZY);

          /* find address of function and data objects */
          fptr = (int (*)(int))dlsym(handle, "some_function");

          iptr = (int *)dlsym(handle, "int_object");

          /* invoke function, passing value of integer as a parameter */

          i = (*fptr)(*iptr);

SEE ALSO
     dlclose(3C), dlerror(3C), dlopen(3C), sgidladd(3C),
     sgigetdsoversion(3C)