Man Pages

dlopen(3p) - phpMan dlopen(3p) - phpMan

Command: man perldoc info search(apropos)  


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 dif-
       fer (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 implementations 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 refer-
       enced 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
       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 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. 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 pro-
              cessing if relocations are performed for functions that are never referenced. This behavior may be  use-
              ful 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 symbols
       loaded with a dlopen() invocation, the mode parameter should be a bitwise-inclusive OR with one of the  follow-
       ing values:

       RTLD_GLOBAL
              The object's symbols shall be made available for the relocation processing of any other object. In addi-
              tion, 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 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 previous or future specifica-
       tion 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 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  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 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 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, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  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 Stan-
       dard,  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)