dlsym(3)						     Library Functions Manual							  dlsym(3)

NAME

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

SYNOPSIS

       #include <dlfcn.h>

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

PARAMETERS

       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

       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().

RETURN VALUE

       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().

ERRORS

       No errors are defined.

EXAMPLES

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

APPLICATION USAGE

       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 flag) - or an
       object that was included in the same dlopen() operation that loaded this one.  The RTLD_NEXT flag 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.

NOTES

       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  com-
       piler 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.

RELATED INFORMATION

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

																	  dlsym(3)