Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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	dynam-
     ically linked program 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 ar-
     gument.  The path argument	can be specified as either an absolute path-
     name 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 im-
     plicitly loaded shared libraries at program 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	or-
     dered set of objects consisting of	the original program image and any de-
     pendencies	loaded during startup.

     The mode parameter	specifies symbol resolution time and symbol visibil-
     ity.  One of the following	values may be used to specify symbol resolu-
     tion 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 depen-
			  dencies will be visible to other objects.

	   RTLD_LOCAL	  The object's symbols and the symbols of its depen-
			  dencies 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	argu-
     ment:

	   RTLD_NODELETE    Prevents unload of the loaded object on dlclose().
			    The	same behaviour 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, oth-
			    erwise 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	dependencies 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-dy-
     namic 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 is-
			   suing 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 ob-
			   ject	issuing	the call to dlsym() and	those shared
			   objects which were loaded after it that are visi-
			   ble.

     dlvsym() does the same as dlsym() but takes a version string as an	addi-
     tional 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	symbol.

     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 li-
     braries where the actual code resides.

     dlctl() provides an interface similar to ioctl(2) to control several as-
     pects 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 invoca-
     tion of dlerror(),	dlerror() returns NULL.	 Thus, invoking	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	gener-
     ated when a program 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

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | ERRORS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dlfcn&sektion=3&manpath=NetBSD+6.0>

home | help