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

FreeBSD Manual Pages


home | help
dlopen(3C)							    dlopen(3C)

       dlopen, dlmopen - gain access to	an executable object file

       #include	<dlfcn.h>
       #include	<link.h>

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

       void * dlmopen(Lmid_t lmid, const char *pathname, int mode);

       The  dlopen()  function	makes an executable object file	available to a
       running process.	dlopen() returns to the	 process  a  handle  that  the
       process	 can   use  on	subsequent  calls  to  dlsym(3C),  dladdr(3C),
       dlinfo(3C), and dlclose(3C). The	value of this handle should not	be in-
       terpreted  in any way by	the process. The pathname argument is the path
       name of the object to be	opened.	A path name containing an embedded '/'
       is  interpreted	as  an absolute	path or	relative to the	current	direc-
       tory. Otherwise,	the set	of search paths	currently  in  effect  by  the
       runtime linker are used to locate the specified file. See NOTES.

       The dlopen() function also loads	any dependencies recorded within path-
       name. These dependencies	are searched in	the order in which the	depen-
       dencies were loaded to locate any additional dependencies. This process
       continues until all the dependencies of pathname	are loaded.  This  de-
       pendency	tree is	referred to as a group.

       If  the	value of pathname is 0,	dlopen() provides a handle on a	set of
       global symbol objects. These objects consist of	the  original  program
       image file, any dependencies loaded at program startup, and any objects
       loaded using dlopen() with the RTLD_GLOBAL flag.	Because	the latter set
       of  objects  can	change during process execution, the set identified by
       handle can also change dynamically.

       The mode	argument describes how dlopen()	operates on pathname with  re-
       spect to	the processing of reference relocations. The mode also affects
       the scope of visibility of the symbols provided by pathname and its de-
       pendencies.  This  visibility  can  affect  how the resulting handle is

       When an object is loaded, the object can	contain	references to  symbols
       whose  addresses	are not	known until the	object is loaded. These	refer-
       ences must be relocated before the symbols can be accessed.  References
       are  categorized	as either immediate or lazy.  Immediate	references are
       typically references to data items used by the object  code.  Immediate
       references  include  pointers  to functions and calls to	functions made
       from position-dependent shared objects. Lazy references	are  typically
       calls  to  global  functions  that  are	made from position-independent
       shared objects. The mode	argument governs when  these  references  take
       place. The mode argument	can be one of the following values:

       RTLD_LAZY       Only immediate symbol references	are relocated when the
		       object is first loaded. Lazy references are  not	 relo-
		       cated  until  a	given function is called for the first
		       time. This value	for mode should	 improve  performance,
		       since  a	 process might not require all lazy references
		       in any given object. This behavior  mimics  the	normal
		       loading	of dependencies	during process initialization.
		       See NOTES.

       RTLD_NOW	       All necessary relocations are performed when the	object
		       is first	loaded.	This process might waste some process-
		       ing if relocations are performed	 for  lazy  references
		       that  are  never	 used. However,	this mode ensures that
		       when an object is loaded, all symbols referenced	during
		       execution are available.	This behavior mimics the load-
		       ing  of	dependencies  when  the	 environment  variable
		       LD_BIND_NOW is in effect.

       See the	for more information about symbol references.

       The  visibility of symbols that are available for relocation can	be af-
       fected by mode. To specify the scope of visibility for symbols that are
       loaded with a dlopen() call, mode should	be a bitwise-inclusive OR with
       one of the following values:

       RTLD_GLOBAL     The object's global symbols are made available for  the
		       relocation processing of	any other object. In addition,
		       symbol lookup using dlopen(0, mode) and	an  associated
		       dlsym() allows objects that are loaded with RTLD_GLOBAL
		       to be searched.

       RTLD_LOCAL      The object's globals symbols are	only available for the
		       relocation processing of	other objects that include the
		       same group.

       The program image file and any objects loaded at	program	 startup  have
       the  mode  RTLD_GLOBAL. The mode	RTLD_LOCAL is the default mode for any
       objects that are	acquired with dlopen().	 A local object	can be	a  de-
       pendency	 of more then one group. Any object of mode RTLD_LOCAL that is
       referenced as a dependency of an	object of mode RTLD_GLOBAL is promoted
       to RTLD_GLOBAL.	In other words,	the RTLD_LOCAL mode is ignored.

       Any  object loaded by dlopen() that requires relocations	against	global
       symbols can reference the symbols in any	RTLD_GLOBAL object. Objects of
       this mode are at	least the program image	file and any objects loaded at
       program startup.	A loaded object	can also reference  symbols  from  it-
       self,  and  from	 any  dependencies the object references. However, the
       mode parameter can also be a bitwise-inclusive OR with one of the  fol-
       lowing values to	affect the scope of symbol availability:

       RTLD_GROUP      Only  symbols from the associated group are made	avail-
		       able for	relocation. A group is	established  from  the
		       defined object and all the dependencies of that object.
		       A group must be completely self-contained.  All	depen-
		       dency  relationships  between  the members of the group
		       must be sufficient to satisfy the  relocation  require-
		       ments of	each object that defines the group.

       RTLD_PARENT     The  symbols of the object initiating the dlopen() call
		       are made	available to the objects obtained by dlopen().
		       This  option is useful when hierarchical	dlopen() fami-
		       lies are	created. Although the parent object can	supply
		       symbols	for  the relocation of this object, the	parent
		       object is not available to dlsym() through the returned

       RTLD_WORLD      Only  symbols  from RTLD_GLOBAL objects are made	avail-
		       able for	relocation.

       The default modes for dlopen() are both RTLD_WORLD and  RTLD_GROUP.  If
       an  object  is requires additional modes, the mode parameter can	be the
       bitwise-inclusive OR of the required modes together  with  the  default

       The  following modes provide additional capabilities outside of reloca-
       tion processing:

       RTLD_NODELETE   The specified object is tagged to prevent its  deletion
		       from the	address	space as part of a dlclose().

       RTLD_NOLOAD     The  specified  object  is  not	loaded	as part	of the
		       dlopen(). However, a valid handle is  returned  if  the
		       object  already	exists	as part	of the process address
		       space. Additional modes can be specified	as a  bitwise-
		       inclusive  OR  with  the	present	mode of	the object and
		       its dependencies. The RTLD_NOLOAD mode provides a means
		       of  querying  the presence or promoting the modes of an
		       existing	dependency.

       The default use of a handle with	dlsym()	allows a symbol	search to  in-
       spect  all  objects  that are associated	with the group of objects that
       are loaded from dlopen(). The mode parameter can	also be	a  bitwise-in-
       clusive OR with the following value to restrict this symbol search:

       RTLD_FIRST      Use  of	this handle with dlsym(), restricts the	symbol
		       search to the first object associated with the handle.

       An object can  be  accessed  from  a  process  both  with  and  without
       RTLD_FIRST. Although the	object will only be loaded once, two different
       handles are created to provide for the different	dlsym()	requirements.

       The dlmopen() function is identical to dlopen(),	except that an identi-
       fying  link-map ID (lmid) is provided. This link-map ID informs the dy-
       namic linking facilities	upon which link-map list to load  the  object.
       See the for details about link-maps.

       The  lmid passed	to dlmopen() identifies	the link-map list on which the
       object is loaded. This parameter	can be any valid  Lmid_t  returned  by
       dlinfo()	or one of the following	special	values:

       LM_ID_BASE      Load the	object on the applications link-map list.

       LM_ID_LDSO      Load  the object	on the dynamic linkers ( link-
		       map list.

       LM_ID_NEWLM     Cause the object	to create a new	link-map list as  part
		       of  loading.  Objects that are opened on	a new link-map
		       list must express all of	their dependencies.

       The dlopen() function returns NULL if pathname cannot be	found,	cannot
       be  opened  for reading,	or is not a shared object or a relocatable ob-
       ject. dlopen() also returns NULL	if an error occurs during the  process
       of  loading  pathname or	relocating its symbolic	references. See	NOTES.
       Additional diagnostic information is available through dlerror().

       The dlopen() and	dlmopen() functions are	members	of a family  of	 func-
       tions  that  give the user direct access	to the dynamic linking facili-
       ties. This family of functions is available only	to  dynamically-linked
       processes. See the .

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |MT-Safe			   |

       ld(1),,  dladdr(3C),	 dlclose(3C), dldump(3C), dlerror(3C),
       dlinfo(3C), dlsym(3C), attributes(5), standards(5)

       If pathname has dependencies on other objects, these objects are	 auto-
       matically  loaded  by  dlopen().	The directory search path used to find
       pathname	and any	dependencies can be affected by	setting	 the  environ-
       ment variable LD_LIBRARY_PATH. Any LD_LIBRARY_PATH variable is analyzed
       once at process startup.	The search path	can also be  affected  from  a
       runpath setting within the object from which the	call to	dlopen() orig-
       inates. These search rules will only be applied to path names  that  do
       not  contain  an	 embedded '/'. Objects whose names resolve to the same
       absolute	path name or relative path name	can be opened  any  number  of
       times  using dlopen(). However, the object that is referenced will only
       be loaded once into the address space of	the current process.

       When loading shared objects, the	application  should  open  a  specific
       version	of the shared object. Do not rely on the version of the	shared
       object pointed to by the	symbolic link.

       When building objects to	be loaded on a new link-map list, some precau-
       tions  need  to be taken. In general, all dependencies must be included
       when building an	object.	Also, include  /usr/lib/  be-
       fore /lib/ when	building an object.

       When an object is loaded	on a new link-map list,	the object is isolated
       from the	main running program. Certain global resources are only	usable
       from  one  link-map list. A few examples	are the	sbrk() based malloc(),
       libthread(), and	the signal vectors. Care must be taken not to use  any
       of these	resources other	than from the primary link-map list. These is-
       sues are	discussed in further detail in the .

       Some symbols defined in dynamic executables or shared objects  can  not
       be  available to	the runtime linker. The	symbol table created by	ld for
       use by the runtime linker might contain only a subset  of  the  symbols
       that are	defined	in the object.

       As  part	of loading a new object, initialization	code within the	object
       is called before	the dlopen()  returns.	This  initialization  is  user
       code,  and  as  such,  can  produce  errors  that  can not be caught by
       dlopen(). For example, an object	loaded using RTLD_LAZY	that  attempts
       to  call	a function that	can not	be located results in process termina-
       tion. Erroneous programming practices within  the  initialization  code
       can  also  result in process termination. The runtime linkers debugging
       facility	can offer help identifying  these  types  of  error.  See  the
       LD_DEBUG	environment variable of

       Loading	relocatable  objects  is  an expensive operation that requires
       converting the relocatable object into a	shared	object	memory	image.
       This  capability	 may  be useful	in a debugging environment, but	is not
       recommended for production software.

				  4 Feb	2005			    dlopen(3C)


Want to link to this manual page? Use this URL:

home | help