dlopen man page on DigitalUNIX

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

dlopen(3)							     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  pro‐
       cessing	of relocations and the scope of visibility of the symbols pro‐
       vided 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  sub‐
       sequent 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 specified
       below (see loader(5) for more details on shared library search directo‐
       ries):

       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 iden‐
       tified 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 speci‐
       fied 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	refer‐
       ences  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  per‐
       formed  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  reloca‐
       tion 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 inter‐
       preted  at  each invocation. Note, however, that once RTLD_NOW has been
       specified, all relocations will have been completed (which renders fur‐
       ther RTLD_NOW operations redundant and any further RTLD_LAZY operations
       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 resolu‐
       tion order. Two such resolution orders are defined, load or  dependency
       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 process‐
       ing.   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	depen‐
       dent  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  relocating  its
       symbolic references

       More  detailed  diagnostic  information will be available through dler‐
       ror().

ERRORS
       No errors are defined.

NOTES
       The dlopen() and dlclose() routines might dynamically change the	 reso‐
       lution of certain symbols referenced by a program or its shared library
       dependencies. The dlopen() routine might resolve symbols that were pre‐
       viously	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 res‐
       olution.

       The  maximum  number  of shared libraries that can be loaded simultane‐
       ously 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.

SEE ALSO
       dlclose(3), dlerror(3), dlsym(3), ld(1), loader(5)

								     dlopen(3)
[top]

List of man pages available for DigitalUNIX

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]
Tweet
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