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



PROLOG
       This  manual page is part of the POSIX Programmer's Man-
       ual.  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 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. Oth-
       erwise, file is used in an implementation-defined manner
       to yield a pathname.

       If the value of file is 0, dlopen() shall provide a han-
       dle 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  execu-
       tion,  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  implementa-
              tion-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 ref-
              erence all of the functions in any given  object.
              And,  for systems supporting dynamic symbol reso-
              lution for normal process execution, this  behav-
              ior  mimics the normal handling of process execu-
              tion.

       RTLD_NOW
              All necessary relocations shall be performed when
              the  object  is first loaded. This may waste some
              processing if relocations are performed for func-
              tions  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  pro-
       gram  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() invoca-
       tion and which specified the RTLD_GLOBAL flag. To deter-
       mine 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 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 opera-
       tions 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 res-
       olution  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 defini-
       tions 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  dependen-
       cies,  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  per-
       formed  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 avail-
       able through dlsym() are at a minimum  those  which  are
       exported as symbols of global scope by the object. Typi-
       cally 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 vol-
       ume 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  Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute  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.open-
       group.org/unix/online.html .



IEEE/The Open Group                  2003                           DLOPEN(3P)
