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

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.

ERRORS
  No errors are defined.

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

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

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

SEE ALSO
  dlclose(3), dlerror(3), dlopen(3).

Index for Section 3

Alphabetical listing for D

Top of page