Index for Section 3

Alphabetical listing for D

Bottom of page

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
  handle
      The value returned from a call to dlopen() (and which has not since
      been released by a call to dlclose()).

  name
      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:

  RTLD_NEXT
    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 compiler 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).

Index for Section 3

Alphabetical listing for D

Top of page