Unix/Linux Go Back    


Linux 2.6 - man page for dlsym (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


DLSYM(P)			    POSIX Programmer's Manual				 DLSYM(P)

NAME
       dlsym - obtain the address of a symbol from a dlopen object

SYNOPSIS
       #include <dlfcn.h>

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

DESCRIPTION
       The  dlsym()  function  shall obtain the address of a symbol defined within an object made
       accessible through a dlopen() call. The handle argument is the value returned from a  call
       to  dlopen()  (and which has not since been released via a call to dlclose()), and name is
       the symbol's name as a character string.

       The dlsym() function shall search for the named symbol in all objects loaded automatically
       as  a  result of loading the object referenced by handle (see dlopen() ). Load ordering is
       used in dlsym() operations upon the global symbol object. The symbol resolution	algorithm
       used shall be dependency order as described in dlopen() .

       The RTLD_DEFAULT and RTLD_NEXT flags are reserved for future use.

RETURN VALUE
       If handle does not refer to a valid object opened by dlopen(), or if the named symbol can-
       not be found within any of the objects associated with handle, dlsym() shall return  NULL.
       More detailed diagnostic information shall be available through dlerror() .

ERRORS
       No errors are defined.

       The following sections are informative.

EXAMPLES
       The following example shows how dlopen() and dlsym() can be used 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", RTLD_LOCAL | RTLD_LAZY);

	      /* find the address of function and data objects */
	      *(void **)(&fptr) = 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_DEFAULT
	      The  symbol lookup happens in the normal global scope; that is, a search for a sym-
	      bol using this handle would find the same definition as a direct use of this symbol
	      in the program code.

       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() ). 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 is an object that was included in the same dlopen() oper-
	      ation 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 alloca-
       tions, 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.

RATIONALE
       The ISO C standard does not require that pointers to functions can be cast back and  forth
       to  pointers  to  data. Indeed, the ISO C standard does not require that an object of type
       void * can hold a pointer to a function. Implementations  supporting  the  XSI  extension,
       however,  do  require  that an object of type void * can hold a pointer to a function. The
       result of converting a pointer to a function into a pointer to another data  type  (except
       void  *) is still undefined, however. Note that compilers conforming to the ISO C standard
       are required to generate a warning if a conversion from a void *  pointer  to  a  function
       pointer is attempted as in:

	      fptr = (int (*)(int))dlsym(handle, "my_function");

       Due  to	the  problem noted here, a future version may either add a new function to return
       function pointers, or the current interface may be deprecated in favor of  two  new  func-
       tions: one that returns data pointers and the other that returns function pointers.

FUTURE DIRECTIONS
       None.

SEE ALSO
       dlclose()  ,  dlerror()	, dlopen() , the Base Definitions volume of IEEE Std 1003.1-2001,
       <dlfcn.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					 DLSYM(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:21 AM.