dlopen man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

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
       interpreted  in	any  way  by the process. The pathname argument is the
       path name of the object to be opened. A path name containing an	embed‐
       ded  '/'	 is interpreted as an absolute path or relative to the current
       directory. 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
       dependency 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
       respect	to  the	 processing  of	 reference  relocations. The mode also
       affects the scope of visibility of the symbols provided by pathname and
       its  dependencies.  This visibility can affect how the resulting handle
       is used.

       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:

		    Only  immediate  symbol  references are relocated when the
		    object is first loaded.  Lazy references are not relocated
		    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.

		    All necessary relocations are performed when the object is
		    first loaded. This process might waste some processing  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 loading	 of  dependen‐
		    cies  when	the  environment  variable  LD_BIND_NOW	 is in

       See the Linker and Libraries Guide for more  information	 about	symbol

       The  visibility	of  symbols  that  are available for relocation can be
       affected 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:

		      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.

		      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 depen‐
       dency  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
       itself,	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:

		      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.

		      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

		      Only symbols from RTLD_GLOBAL objects are made available
		      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:

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

			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
       inspect	all objects that are associated with the group of objects that
       are loaded from dlopen(). The mode parameter can	 also  be  a  bitwise-
       inclusive OR with the following value to restrict this symbol search:

		     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
       dynamic linking facilities upon which link-map list to load the object.
       See the Linker and Libraries Guide 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:

		      Load the object on the applications link-map list.

		      Load  the	 object on the dynamic linkers (ld.so.1) link-
		      map list.

		      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
       object. 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	 dler‐

       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 Linker and Libraries Guide.

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

       │Interface Stability │ Standard	      │
       │MT−Level	    │ MT−Safe	      │

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

       Linker and Libraries Guide

       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/libmapmalloc.so.1
       before /lib/libc.so.1 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
       issues  are  discussed  in  further  detail in the Linker and Libraries

       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 ld.so.1(1).

       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.

				  Feb 4, 2005			    DLOPEN(3C)

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net