👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for dlerror (netbsd section 3)

DLFCN(3)			   BSD Library Functions Manual 			 DLFCN(3)

NAME
     dlopen, dlclose, dlsym, dlvsym, dladdr, dlctl, dlerror -- dynamic link interface

LIBRARY
     (These functions are not in a library.  They are included in every dynamically linked pro-
     gram automatically.)

SYNOPSIS
     #include <dlfcn.h>

     void *
     dlopen(const char *path, int mode);

     int
     dlclose(void *handle);

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

     void *
     dlvsym(void * restrict handle, const char * restrict symbol, const char *version);

     int
     dladdr(void * restrict addr, Dl_info * restrict dli);

     int
     dlctl(void *handle, int cmd, void *data);

     char *
     dlerror(void);

DESCRIPTION
     These functions provide an interface to the run-time linker ld.so(1).  They allow new shared
     objects to be loaded into the process' address space under program control.

     The dlopen() function takes the name of a shared object as the first argument.  The path
     argument can be specified as either an absolute pathname to a shared object or just the name
     of the shared object itself.  When an absolute pathname is specified, only the path provided
     will be searched.	When just a shared object name is specified, the same search rules apply
     that are used for ``intrinsic'' shared object searches.  (see ld.elf_so(1))

     Shared libraries take the following form: ``lib<name>.so[.xx[.yy]]''.

     The shared object is mapped into the address space, relocated, and its external references
     are resolved in the same way as is done with the implicitly loaded shared libraries at pro-
     gram startup.

     If the first argument is NULL, dlopen() returns a handle on the global symbol object.  This
     object provides access to all symbols from an ordered set of objects consisting of the orig-
     inal program image and any dependencies loaded during startup.

     The mode parameter specifies symbol resolution time and symbol visibility.  One of the fol-
     lowing values may be used to specify symbol resolution time:

	   RTLD_NOW	  Symbols are resolved immediately.

	   RTLD_LAZY	  Symbols are resolved when they are first referred to.  This is the
			  default value if resolution time is unspecified.

     One of the following values may be used to specify symbol visibility:

	   RTLD_GLOBAL	  The object's symbols and the symbols of its dependencies will be visi-
			  ble to other objects.

	   RTLD_LOCAL	  The object's symbols and the symbols of its dependencies will not be
			  visible to other objects.  This is the default value if visibility is
			  unspecified.

     To specify both resolution time and visibility, bitwise inclusive OR one of each of the
     above values together.  If an object was opened with RTLD_LOCAL and later opened with
     RTLD_GLOBAL, then it is promoted to RTLD_GLOBAL.

     Additionally, one of the following flags may be ORed into the mode argument:

	   RTLD_NODELETE    Prevents unload of the loaded object on dlclose().	The same behav-
			    iour may be requested by -z nodelete option of the static linker
			    ld(1).

	   RTLD_NOLOAD	    Only return valid handle for the object if it is already loaded in
			    the process address space, otherwise do not load the object and
			    return NULL.

     dlopen() returns a handle to be used in calls to dlclose(), dlsym(), dlvsym(), and dlctl().
     If the named shared object has already been loaded by a previous call to dlopen() (and not
     yet unloaded by dlclose()), a handle referring to the resident copy is returned.

     dlclose() unlinks and removes the object referred to by handle from the process address
     space.  If multiple calls to dlopen() have been done on this object, or the object was one
     loaded at startup time, or the object is a dependency of another object then the object is
     removed when its reference count drops to zero.  dlclose() returns 0 on success and non-zero
     on failure.

     dlsym() looks for a definition of symbol in the shared object designated by handle, and all
     shared objects that are listed as dependencies.  The symbol's address is returned.  If the
     symbol cannot be resolved, NULL is returned.

     dlsym() may also be called with special handle values.  dlsym() respects symbol visibility
     as specified by the dlopen() mode parameter.  However, the symbols of an object's dependen-
     cies are always visible to it.  All shared objects loaded at program startup are globally
     visible.  Only the symbols in the main executable that are referenced by a shared object at
     link time will be visible unless it has been linked with the --export-dynamic option where
     all of its symbols will be visible.  The following special handle values may be used with
     dlsym():

	   NULL 	   Interpreted as a reference to the executable or shared object from
			   which the call is being made.  Thus an object can reference its own
			   symbols and the symbols of its dependencies without calling dlopen().

	   RTLD_DEFAULT    All the visible shared objects and the executable will be searched in
			   the order they were loaded.

	   RTLD_NEXT	   The search for symbol is limited to the visible shared objects which
			   were loaded after the one issuing the call to dlsym().  Thus, if
			   dlsym() is called from the main program, all the visible shared
			   libraries are searched.  If it is called from a shared library, all
			   subsequently visible shared libraries are searched.

	   RTLD_SELF	   The search for symbol is limited to the shared object issuing the call
			   to dlsym() and those shared objects which were loaded after it that
			   are visible.

     dlvsym() does the same as dlsym() but takes a version string as an additional argument.
     Both the symbol and the version must match in order for the symbol to be resolved.

     dladdr() examines all currently mapped shared objects for a symbol whose address -- as
     mapped in the process address space -- is closest to but not exceeding the value passed in
     the first argument addr.  The symbols of a shared object are only eligible if addr is
     between the base address of the shared object and the value of the symbol ``_end'' in the
     same shared object.  If no object for which this condition holds true can be found, dladdr()
     will return 0.  Otherwise, a non-zero value is returned and the dli argument will be used to
     provide information on the selected symbol and the shared object it is contained in.  The
     dli argument points at a caller-provided Dl_info structure defined as follows:

	   typedef struct {
		   const char  *dli_fname;     /* File defining the symbol */
		   void        *dli_fbase;     /* Base address */
		   const char  *dli_sname;     /* Symbol name */
		   const void  *dli_saddr;     /* Symbol address */
	   } Dl_info;

     The structure members are further described as follows:

     dli_fname	  The pathname of the shared object containing the address addr.

     dli_fbase	  The base address at which this shared object is loaded in the process address
		  space.  This may be zero if the symbol was found in the internally generated
		  ``copy'' section (see link(5)) which is not associated with a file.

     dli_sname	  points at the nul-terminated name of the selected symbol

     dli_saddr	  is the actual address (as it appears in the process address space) of the sym-
		  bol.

     Note: both strings pointed at by dli_fname and dli_sname reside in memory private to the
     run-time linker module and should not be modified by the caller.

     In dynamically linked programs, the address of a global function will point to its program
     linkage table entry, rather than to the entry point of the function itself.  This causes
     most global functions to appear to be defined within the main executable, rather than in the
     shared libraries where the actual code resides.

     dlctl() provides an interface similar to ioctl(2) to control several aspects of the run-time
     linker's operation.  This interface is currently under development.

     dlerror() returns a character string representing the most recent error that has occurred
     while processing one of the other functions described here.  If no dynamic linking errors
     have occurred since the last invocation of dlerror(), dlerror() returns NULL.  Thus, invok-
     ing dlerror() a second time, immediately following a prior invocation, will result in NULL
     being returned.

ERRORS
     The error ``Cannot dlopen non-loadable /usr/lib/libpthread.so.1'' is generated when a pro-
     gram dlopen()s a module that needs libpthread but isn't linked against it itself.

SEE ALSO
     ld(1), rtld(1), link(5)

HISTORY
     Some of the dl* functions first appeared in SunOS 4.

BSD					  June 25, 2011 				      BSD


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

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password