DLOPEN(3P) - phpMan

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

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
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 imple-
       mentations 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 con-
       struction  of  programs  that  can employ dlopen() and its related ser-
       vices.
       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 latter 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 processing 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 parame-
       ter governs when these relocations take place and may have the  follow-
       ing 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. Specifying 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 reference 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() invocation,  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 sym-
       bols  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 reloca-
              tion processing of any other object.

       If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, then an  implemen-
       tation-defined default behavior shall be applied.
       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 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 pre-
       vious  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 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 (via 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 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  depen-
       dent  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 minimum those which are exported as symbols of global
       scope by the object. Typically such symbols 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 implementa-
       tion.
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 infor-
       mation 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 original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                           DLOPEN(3P)