*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> dlopen (3)              



NAME    [Toc]    [Back]

       dlopen - gain access to an executable object file

SYNOPSIS    [Toc]    [Back]

       #include <dlfcn.h>

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

PARAMETERS    [Toc]    [Back]

       Used  to  construct  a pathname to an object file.  Determines
 how dlopen() will operate upon  the  specified  file
       with  respect  to  the  processing  of relocations and the
       scope of visibility of the  symbols  provided  within  the

DESCRIPTION    [Toc]    [Back]

       The  dlopen  function provides an interface to the dynamic
       library loader to allow shared libraries to be loaded  and
       called at run time. The dlopen() function attempts to load
       the specified file in the address space  of  the  process,
       resolving  symbols as appropriate.  Any libraries that the
       specified file depends upon are also loaded.

       A successful dlopen() returns a handle that the caller can
       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 it includes a  slash  character  (/),  the
       file argument is used as the pathname for the file. Otherwise,
 dlopen() will  attempt  to  locate  the  file  using
       shared  library  search directories in the order specified
       below (see loader(5) for more details  on  shared  library
       search directories):

       The  current  directory  The  program's  rpath directories
       LD_LIBRARY_PATH directories Default shared library  directories

       If  the  value of file is 0, dlopen provides a handle on a
       global symbol object. This object provides access  to  the
       symbols  from  an ordered set of objects consisting of the
       original program image file,  together  with  any  objects
       loaded  at  program  startup  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 the 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 or if  different  pathnames
       are used to reference the file.

       The  mode  parameter  describes  how dlopen() will operate
       upon the specified file with respect to the processing  of
       relocations  and  the  scope  of visibility of the symbols
       provided within the 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 must be relocated before the
       symbols can be accessed. The mode parameter  governs  when
       these  relocations  take  place and may have the following

       The run-time loader performs relocations only  as  needed.
       Typically, this means that the first call to a function in
       the newly loaded library will cause the resolution of  the
       address  of that function to occur.  All necessary relocations
 are performed when the object is first loaded.  This
       may waste some processing if relocations are performed for
       functions that are never referenced. This behaviour may be
       useful  for  applications that need to know, as soon as an
       object is loaded, that all symbols referenced during  execution
 will be 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 startup, from the object itself as well
       as any other object included in the same dlopen()  invocation
  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 bitwise ORed with one of the following values:

       The object's symbols are 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.   The
       object's symbols are not made available for the relocation
       processing of any other object.

       If  neither  RTLD_GLOBAL  nor  RTLD_LOCAL  are  specified,
       RTLD_GLOBAL will be assumed. However, unlike explicit  use
       of  RTLD_GLOBAL,  this  default  mode  will  allow dynamic
       rebinding of symbol addresses and recalculation of dynamic
       relocations as shared libraries are loaded or unloaded.

       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
       will have been completed (which renders  further  RTLD_NOW
       operations  redundant and any further RTLD_LAZY operations
       irrelevant). Also note  that  once  RTLD_GLOBAL  has  been
       specified, the object will maintain the RTLD_GLOBAL status
       regardless of any  previous  or  future  specification  of
       RTLD_LOCAL,  so  long as the object remains in the address
       space (see dlclose(3)).

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

RETURN VALUE    [Toc]    [Back]

       The  dlopen  function will return NULL under the following

       If the specified file cannot be found,  cannot  be  opened
       for reading, or is not of an appropriate object format for
       processing by dlopen() If an error occurs during the  process
 of loading the file or relocating its symbolic references

       More detailed diagnostic  information  will  be  available
       through dlerror().

ERRORS    [Toc]    [Back]

       No errors are defined.

NOTES    [Toc]    [Back]

       The  dlopen()  and  dlclose()  routines  might dynamically
       change the resolution of certain symbols referenced  by  a
       program  or  its shared library dependencies. The dlopen()
       routine might resolve symbols that were  previously  unresolved,
  and  dlclose()  might  cause  resolved symbols to
       become unresolved or to be reresolved to a different  symbol

       Dynamic  symbol resolution functions reliably for programs
       compiled with the -O0 flag. Also,  routines  that  do  not
       call dlopen() or dlclose(), either directly or indirectly,
       can safely depend on dynamic symbol resolution.

       The maximum number of shared libraries that can be  loaded
       simultaneously  by  a  single process is approximately 60.
       This limit can be raised by reconfiguring the kernel's vmmapentries
  parameter.  This parameter should be set to at
       least three times the desired  maximum  number  of  shared
       libraries  that can be loaded by a process. See the manual
       System Administration for  instructions  on  reconfiguring
       the vm-mapentries parameter.

SEE ALSO    [Toc]    [Back]

       dlclose(3), dlerror(3), dlsym(3), ld(1), loader(5)

[ Back ]
 Similar pages
Name OS Title
runexec IRIX run an executable program described in an executable descriptor file
rqs IRIX Make 32-bit executable or shared object QUICKSTARTable
rqs64 IRIX Fixes up 64-bit executable or shared object to be QUICKSTARTable
elf IRIX object file access library
st_get_version_byname Tru64 access version information in an object file
st_get_known_versions Tru64 access version information in an object file
st_mem_get_format_versions Tru64 access version information in an object file
st_mem_get_version_byname Tru64 access version information in an object file
st_fd_get_version_byname Tru64 access version information in an object file
ldfcn Tru64 Common object file access routines
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service