dlopen(3)						     Library Functions Manual							 dlopen(3)

NAME

       dlopen - Gain access to an executable object file

SYNOPSIS

       #include <dlfcn.h>

       void *dlopen(const char *file, int mode)

PARAMETERS

       Used  to construct a pathname to an object file.  Determines how dlopen() will operate upon the specified file with respect to the process-
       ing of relocations and the scope of visibility of the symbols provided within the file.

DESCRIPTION

       The dlopen function provides an interface to the dynamic library loader to allow shared libraries to be loaded and called at run time.  The
       dlopen  function  attempts to load the specified file in the address space of the process, resolving symbols as appropriate.  Any libraries
       that the specified file depends upon are also loaded.

       A successful dlopen() returns a handle that the caller can use on subsequent calls to dlsym() and  dlclose().  The  value  of  this  handle
       should not be interpreted in any way by the caller.

       The  file  argument is used to construct a pathname to the object file.	If it includes a slash character (/), the file argument is used as
       the pathname for the file.  Otherwise, dlopen will attempt to locate the file using shared library search directories in the  order  speci-
       fied  below  (see  loader(5)  for more details on shared library search directories): The current directory The program's rpath directories
       LD_LIBRARY_PATH directories Default shared library directories

       If the value of file is 0, dlopen provides a handle on a global symbol object. This object provides access to the symbols from  an  ordered
       set  of	objects  consisting  of  the original program image file, together with any objects loaded at program startup as specified by that
       process image file (for example, shared libraries), and the set of objects loaded using a dlopen operation together  with  the  RTLD_GLOBAL
       flag. As the latter set of objects can change during execution, the set identified by the handle can also change dynamically.

       Only  a	single	copy  of an object file is brought into the address space - even if dlopen() is invoked multiple times in reference to the
       file or if different pathnames are used to reference the file.

       The mode parameter describes how dlopen() will operate upon the specified file with respect to the processing of relocations and the  scope
       of  visibility of the symbols provided within the file.	When an object is brought into the address space of a process, it may contain ref-
       erences to symbols whose addresses are not known until the object is loaded. These references must be relocated before the symbols  can	be
       accessed.  The  mode  parameter	governs  when these relocations take place and may have the following values: The run-time loader performs
       relocations only as needed. Typically, this means that the first call to a function in the newly loaded library will cause  the	resolution
       of  the	address  of  that function to occur.  All necessary relocations are performed when the object is first loaded. This may waste some
       processing if relocations are performed for functions that are never referenced. This behaviour may be useful for applications that need to
       know, as soon as an object is loaded, that all symbols referenced during execution will be available.

       Any  object  loaded  by	dlopen() that requires relocations against global symbols can reference: The symbols in the original process image
       file Any objects loaded at program startup, from the object itself as well as any other object included in the same dlopen() invocation Any
       objects that were loaded in any dlopen() invocation and which specified the RTLD_GLOBAL flag.

       To  determine the scope of visibility for the symbols loaded with a dlopen() invocation, the mode parameter should be bitwise ORed with one
       of the following values: The object's 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 loaded with this mode to be searched.  The object's symbols are not
       made available for the relocation processing of any other object.

       If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, RTLD_GLOBAL will be assumed. However, unlike explicit use of RTLD_GLOBAL, this default
       mode will allow dynamic rebinding of symbol addresses and recalculation of dynamic relocations as shared libraries are loaded or unloaded.

       If a file is specified in multiple dlopen() invocations, mode is interpreted at each invocation. Note, however, that once RTLD_NOW has been
       specified, all relocations will have been completed (which renders further RTLD_NOW operations redundant and any further  RTLD_LAZY  opera-
       tions  irrelevant).  Also  note that once RTLD_GLOBAL has been specified, the object will maintain the RTLD_GLOBAL status regardless of any
       previous or future specification of RTLD_LOCAL, so long as the object remains in the address space (see dlclose(3)).

       Symbols introduced into a program by calls to dlopen() may be used in relocation activities. Symbols so introduced  may	duplicate  symbols
       already	defined  by the program or previous dlopen() operations. To resolve the ambiguities such a situation might present, the resolution
       of a symbol reference to symbol definition is based on a symbol resolution order. Two such resolution orders are defined,  load	or  depen-
       dency  ordering:  Load order establishes an ordering among symbol definitions, such that the definition first loaded (including definitions
       from the image file and any dependent objects loaded with it) has priority over objects added later (by dlopen()). Load ordering is used in
       relocation processing.  Dependency ordering uses a breadth-first order starting with a given object, then all of its dependencies, then any
       dependents of those, iterating until all dependencies are satisfied.

       With the exception of the global symbol object obtained by a dlopen() operation on a file of 0, dependency ordering is used by the  dlsym()
       function. Load ordering is used in dlsym() operations upon the global symbol object.

       When  an  object is first made accessible by dlopen(), it and its dependent objects are added in dependency order. Once all the objects are
       added, relocations are performed using load ordering.  Note that if an object or its dependencies had been previously loaded, the load  and
       dependency orders may yield different resolutions.

RETURN VALUE

       The  dlopen  function will return NULL under the following conditions: If the specified file cannot be found, cannot be opened for reading,
       or is not of an appropriate object format for processing by dlopen() If an error occurs during the process of loading the file or  relocat-
       ing its symbolic references

       More detailed diagnostic information will be available through dlerror().

ERRORS

       No errors are defined.

NOTES

       The  dlopen  and  dlclose routines might dynamically change the resolution of certain symbols referenced by a program or its shared library
       dependencies. The dlopen routine might resolve symbols that were previously unresolved, and dlclose might cause resolved symbols to  become
       unresolved or to be reresolved to a different symbol definition.

       Dynamic	symbol	resolution  functions reliably for programs compiled with the -O0 flag. Also, routines that do not call dlopen or dlclose,
       either directly or indirectly, can safely depend on dynamic symbol resolution.

       The maximum number of shared libraries that can be loaded simultaneously by a single process is approximately 60. This limit can be  raised
       by  reconfiguring  the kernel's vm-mapentries parameter. This parameter should be set to at least three times the desired maximum number of
       shared libraries that can be loaded by a process. See the manual System Administration for instructions on reconfiguring the  vm-mapentries
       parameter.

RELATED INFORMATION

       dlclose(3), dlerror(3), dlsym(3), ld(1), loader(5).  delim off

																	 dlopen(3)