👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for dlopen (linux section 3posix)

DLOPEN(P)			    POSIX Programmer's Manual				DLOPEN(P)

NAME
       dlopen - gain access to an executable object file

SYNOPSIS
       #include <dlfcn.h>

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

DESCRIPTION
       The  dlopen() function shall make an executable object file specified by file available to
       the calling program. The class of files eligible for this  operation  and  the  manner  of
       their  construction are implementation-defined, though typically such files are executable
       objects such as shared libraries, relocatable files, or programs. Note that some implemen-
       tations	permit	the  construction  of dependencies between such objects that are embedded
       within files. In such cases, a dlopen() operation shall load such dependencies in addition
       to the object referenced by file.  Implementations may also impose specific constraints on
       the construction of programs that can employ dlopen() and its related services.

       A successful dlopen() shall return a handle which the caller may 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 file  contains	a
       slash  character,  the file argument is used as the pathname for the file. Otherwise, file
       is used in an implementation-defined manner to yield a pathname.

       If the value of file is 0, dlopen() shall provide a handle on a global symbol object. This
       object  shall  provide  access to the symbols from an ordered set of objects consisting of
       the original program image file, together with any objects loaded at program  start-up  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  lat-
       ter  set  of  objects  can  change during execution, the set identified by 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, and even if different pathnames are
       used to reference the file.

       The mode parameter describes how dlopen() shall operate upon file with respect to the pro-
       cessing	of  relocations  and the scope of visibility of the symbols provided within file.
       When an object is brought into the address space of a process, it may  contain  references
       to  symbols  whose  addresses  are  not known until the object is loaded. These references
       shall be relocated before the symbols can be accessed. The  mode  parameter  governs  when
       these relocations take place and may have the following values:

       RTLD_LAZY
	      Relocations  shall be performed at an implementation-defined time, ranging from the
	      time of the dlopen() call until the first reference to a given symbol occurs. Spec-
	      ifying  RTLD_LAZY  should improve performance on implementations supporting dynamic
	      symbol binding as a process may not reference all of the	functions  in  any  given
	      object.  And,  for  systems supporting dynamic symbol resolution for normal process
	      execution, this behavior mimics the normal handling of process execution.

       RTLD_NOW
	      All necessary relocations shall be performed when the object is first loaded.  This
	      may waste some processing if relocations are performed for functions that are never
	      referenced. This behavior may be useful for applications that need to know as  soon
	      as an object is loaded that all symbols referenced during execution are available.

       Any  object loaded by dlopen() that requires relocations against global symbols can refer-
       ence the symbols in the original process image file, any objects loaded at program  start-
       up, from the object itself as well as any other object included in the same dlopen() invo-
       cation, and 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 a bitwise-inclusive OR with one  of  the
       following values:

       RTLD_GLOBAL
	      The  object's  symbols shall be 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.

       RTLD_LOCAL
	      The  object's  symbols shall not be made available for the relocation processing of
	      any other object.

       If neither RTLD_GLOBAL  nor  RTLD_LOCAL	are  specified,  then  an  implementation-defined
       default behavior shall be applied.

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

       Symbols introduced into a program through 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 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 (via dlopen()). Load ordering is used in relocation pro-
       cessing. 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  via  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 via dlopen() it	and  its  dependent  objects  are
       added in dependency order. Once all the objects are added, relocations are performed using
       load order.  Note that if an object or its dependencies had been  previously  loaded,  the
       load and dependency orders may yield different resolutions.

       The symbols introduced by dlopen() operations and available through dlsym() are at a mini-
       mum those which are exported as symbols of global scope by the object. Typically such sym-
       bols  shall  be	those that were specified in (for example) C source code as having extern
       linkage.  The precise manner in which an implementation constructs  the	set  of  exported
       symbols for a dlopen() object is specified by that implementation.

RETURN VALUE
       If  file  cannot  be  found, cannot be opened for reading, is not of an appropriate object
       format for processing by dlopen(), or if an error occurs during	the  process  of  loading
       file  or  relocating  its  symbolic  references, dlopen() shall return NULL. More detailed
       diagnostic information shall be available through dlerror() .

ERRORS
       No errors are defined.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       dlclose() , dlerror() , dlsym() , the Base  Definitions	volume	of  IEEE Std 1003.1-2001,
       <dlfcn.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					DLOPEN(P)


All times are GMT -4. The time now is 04:18 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password