dlsym(3C)						   Standard C Library Functions 						 dlsym(3C)

NAME

       dlsym - get the address of a symbol in a shared object or executable

SYNOPSIS

       #include <dlfcn.h>

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

DESCRIPTION

       The  dlsym()  function  allows a process to obtain the address of a symbol that is defined within a shared object or executable. The handle
       argument is either the value returned from a call to dlopen() or one of a family of special handles. The name argument is the symbol's name
       as a character string.

       If  handle is returned from dlopen(), the associated shared object must not have been closed using dlclose(). A handle can be obtained from
       dlopen() using the RTLD_FIRST mode. With this mode, the dlsym() function searches for the named symbol in the initial object referenced	by
       handle.	Without  this  mode,  the  dlsym() function searches for the named symbol in the group of shared objects loaded automatically as a
       result of loading the object referenced by handle. See dlopen(3C) and NOTES.

       The following special handles are supported.

       RTLD_DEFAULT    Instructs dlsym() to search for the named symbol starting with the first object loaded, typically the  dynamic  executable.
		       The  search  continues  through	the list of initial dependencies that are loaded with the process, followed by any objects
		       obtained with dlopen(3C). This search follows the default model that is used to relocate all objects within the process.

		       This model also provides for transitioning into a lazy loading environment. If a symbol can not be found in  the  presently
		       loaded  objects, any pending lazy loaded objects are processed in an attempt to locate the symbol. This loading compensates
		       for objects that have not fully defined their dependencies. However, this compensation can undermine the advantages of lazy
		       loading.

       RTLD_PROBE      Instructs  dlsym() to search for the named symbol in the same manner as occurs with a handle of RTLD_DEFAULT. However, this
		       model only searches for symbols in the presently loaded objects, together with any lazy loadable objects specifically iden-
		       tified by the caller to provide the named symbol. This handle does not trigger an exhaustive load of any lazy loadable sym-
		       bols in an attempt to find the named symbol. This handle  can  provide  a  more	optimal  search  than  would  occur  using
		       RTLD_DEFAULT.

       RTLD_NEXT       Instructs  dlsym()  to  search  for  the  named	symbol in the objects that were loaded following the object from which the
		       dlsym() call is being made.

       RTLD_SELF       Instructs dlsym() to search for the named symbol in the objects that were loaded starting with the object  from	which  the
		       dlsym() call is being made.

       When used with a special handle, dlsym() is selective in searching objects that have been loaded using dlopen(). These objects are searched
       for symbols if one of the following conditions are true.

	   o	  The object is part of the same local dlopen() dependency hierarchy as the calling object. See the Linker and Libraries Guide for
		  a description of dlopen() dependency hierarchies.

	   o	  The object has global search access. See dlopen(3C) for a discussion of the RTLD_GLOBAL mode.

RETURN VALUES

       The  dlsym()  function returns NULL if handle does not refer to a valid object opened by dlopen() or is not one of the special handles. The
       function also returns NULL if the named symbol cannot be found within any of the objects  associated  with  handle.  Additional	diagnostic
       information is available through dlerror(3C).

EXAMPLES

       Example 1 Use dlopen() and dlsym() to access a function or data objects.

       The  following  code fragment demonstrates how to 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);

       Example 2 Use dlsym() to verify that a particular function is defined.

       The following code fragment shows how to use dlsym() to verify that a function is defined. If the function exists, the function is called.

	 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 facilities.  These	facilities
       are available to dynamically-linked processes only. See the Linker and Libraries Guide.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       ld(1), ld.so.1(1), dladdr(3C), dlclose(3C), dldump(3C), dlerror(3C), dlinfo(3C), dlopen(3C), attributes(5), standards(5)

       Linker and Libraries Guide

NOTES

       If  an  object  is  acting  as  a  filter, care should be taken when interpreting the address of any symbol obtained using a handle to this
       object. For example, using dlsym(3C) to obtain the symbol _end for this object, results in returning the address of the symbol _end  within
       the filtee, not the filter. For more information on filters see the Linker and Libraries Guide.

SunOS 5.11							    26 Sep 2005 							 dlsym(3C)