# dlopen

## 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 — open a symbol table handle
    


## SYNOPSIS



           #include <dlfcn.h>
    
           void *dlopen(const char *_file_ , int _mode_);
    


## DESCRIPTION



           The _dlopen_() function shall make the symbols (function identifiers
           and data object identifiers) in the executable object file
           specified by _file_ available to the calling program.
    
           The class of executable object files eligible for this operation
           and the manner of their construction are implementation-defined,
           though typically such files are shared libraries or programs.
    
           Implementations may permit the construction of embedded
           dependencies in executable object files. In such cases, a _dlopen_()
           operation shall load those dependencies in addition to the
           executable object file specified 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 symbol table handle which the
           caller may use on subsequent calls to _dlsym_() and _dlclose_().
    
           The value of this symbol table handle should not be interpreted in
           any way by the caller.
    
           The _file_ argument is used to construct a pathname to the
           executable 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 _file_ is a null pointer, _dlopen_() shall return a global symbol
           table handle for the currently running process image. This symbol
           table handle shall provide access to the symbols from an ordered
           set of executable object files consisting of the original program
           image file, any executable object files loaded at program start-up
           as specified by that process file (for example, shared libraries),
           and the set of executable object files loaded using _dlopen_()
           operations with the RTLD_GLOBAL flag. As the latter set of
           executable object files can change during execution, the set of
           symbols made available by this symbol table handle can also change
           dynamically.
    
           Only a single copy of an executable object file shall be brought
           into the address space, even if _dlopen_() is invoked multiple times
           in reference to the executable object file, and even if different
           pathnames are used to reference the executable object 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
           executable object file is brought into the address space of a
           process, it may contain references to symbols whose addresses are
           not known until the executable object file 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 since a process might not reference all
                       of the symbols in an executable object file. 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
                       executable object file is first loaded. This may waste
                       some processing if relocations are performed for
                       symbols that are never referenced. This behavior may
                       be useful for applications that need to know that all
                       symbols referenced during execution will be available
                       before _dlopen_() returns.
    
           Any executable object file loaded by _dlopen_() that requires
           relocations against global symbols can reference the symbols in
           the original process image file, any executable object files
           loaded at program start-up, from the initial process image itself,
           from any other executable object file included in the same
           _dlopen_() invocation, and any executable object files 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 executable object file's symbols shall be made
                       available for relocation processing of any other
                       executable object file. In addition, symbol lookup
                       using _dlopen_(NULL,_mode_) and an associated _dlsym_()
                       allows executable object files loaded with this mode
                       to be searched.
    
           RTLD_LOCAL  The executable object file's symbols shall not be made
                       available for relocation processing of any other
                       executable object file.
    
           If neither RTLD_GLOBAL nor RTLD_LOCAL is specified, the default
           behavior is unspecified.
    
           If an executable object file is specified in multiple _dlopen_()
           invocations, _mode_ is interpreted at each invocation.
    
           If RTLD_NOW has been specified, all relocations shall have been
           completed rendering further RTLD_NOW operations redundant and any
           further RTLD_LAZY operations irrelevant.
    
           If RTLD_GLOBAL has been specified, the executable object file
           shall maintain the RTLD_GLOBAL status regardless of any previous
           or future specification of RTLD_LOCAL, as long as the executable
           object file remains in the address space (see dlclose(3p)).
    
           Symbols introduced into the process image 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 order and dependency order.
           Load order establishes an ordering among symbol definitions, such
           that the first definition loaded (including definitions from the
           process image file and any dependent executable object files
           loaded with it) has priority over executable object files added
           later (by _dlopen_()).  Load ordering is used in relocation
           processing. Dependency ordering uses a breadth-first order
           starting with a given executable object file, then all of its
           dependencies, then any dependents of those, iterating until all
           dependencies are satisfied. With the exception of the global
           symbol table handle obtained via a _dlopen_() operation with a null
           pointer as the _file_ argument, dependency ordering is used by the
           _dlsym_() function. Load ordering is used in _dlsym_() operations upon
           the global symbol table handle.
    
           When an executable object file is first made accessible via
           _dlopen_(), it and its dependent executable object files are added
           in dependency order. Once all the executable object files are
           added, relocations are performed using load order. Note that if an
           executable object file 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
           identifiers of global scope by the executable object file.
           Typically, such identifiers 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 an executable object file is implementation-defined.
    


## RETURN VALUE



           Upon successful completion, _dlopen_() shall return a symbol table
           handle. If _file_ cannot be found, cannot be opened for reading, is
           not of an appropriate executable object file format for processing
           by _dlopen_(), or if an error occurs during the process of loading
           _file_ or relocating its symbolic references, _dlopen_() shall return
           a null pointer. More detailed diagnostic information shall be
           available through _dlerror_().
    


## ERRORS



           No errors are defined.
    
           _The following sections are informative._
    


## EXAMPLES



           Refer to dlsym(3p).
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *