dlopen(3X)      UNIX System V(C Programming Language Utilities)      dlopen(3X)


NAME
      dlopen - open a shared object

SYNOPSIS
      cc [flag ...] file ...  -ldl [library ...]

      #include <dlfcn.h>

      void *dlopen(char *pathname, int mode);

DESCRIPTION
      dlopen is one of a family of routines that give the user direct access to
      the dynamic linking facilities.  (See ``C Compilation System'' in the
      Programmer's Guide: ANSI C and Programming Support Tools).  These
      routines are available in a library that is loaded if the option -ldl is
      used with cc or ld.

      dlopen makes a shared object available to a running process.  dlopen
      returns to the process a handle the process may use on subsequent calls
      to dlsym and dlclose.  This value should not be interpreted in any way by
      the process.  pathname is the path name of the object to be opened; it
      may be an absolute path or relative to the current directory.  If the
      value of pathname is 0, dlopen makes the symbols contained in the
      original a.out, and all of the objects that were loaded at program
      startup with the a.out, available through dlsym.

      When a shared 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 values:

      RTLDLAZY
            Under this mode, only references to data symbols are relocated when
            the object is loaded.  References to functions are not relocated
            until a given function is invoked for the first time.  This mode
            should result in better performance, since a process may not
            reference all of the functions in any given shared object.

      RTLDNOW
            Under this mode, all necessary relocations are performed when the
            object is first loaded.  This may result in some wasted effort, if
            relocations are performed for functions that are never referenced,
            but is useful for applications that need to know as soon as an
            object is loaded that all symbols referenced during execution will
            be available.

SEE ALSO
      cc(1), ld(1), sh(1), exec(2), dlclose(3X), dlerror(3X), dlsym(3X).
      The ``C Compilation System'' chapter in the Programmer's Guide: ANSI C
      and Programming Support Tools.



10/89                                                                    Page 1

dlopen(3X)      UNIX System V(C Programming Language Utilities)      dlopen(3X)


DIAGNOSTICS
      If pathname cannot be found, cannot be opened for reading, is not a
      shared object, or if an error occurs during the process of loading
      pathname or relocating its symbolic references, dlopen returns NULL.
      More detailed diagnostic information is available through dlerror.

NOTES
      If other shared objects were link edited with pathname when pathname was
      built, those objects are automatically loaded by dlopen.  The directory
      search path to be used to find both pathname and the other needed objects
      may be specified by setting the environment variable LDLIBRARYPATH.
      This environment variable should contain a colon-separated list of
      directories, in the same format as the PATH variable [see sh(1)].
      LDLIBRARYPATH is ignored if the process is running setuid or setgid
      [see exec(2)] or if the name specified is not a simple file name (that
      is, contains a / character).  Objects whose names resolve to the same
      absolute or relative path name may be opened any number of times using
      dlopen, however, the object referenced is loaded only once into the
      address space of the current process.  The same object referenced by two
      different path names, however, may be loaded multiple times.  For
      example, given the object /usr/home/me/mylibs/mylib.so, and assuming the
      current working directory is /usr/home/me/workdir,

            . . .
            void *handle1;
            void *handle2;

            handle1 = dlopen("../mylibs/mylib.so", RTLDLAZY);
            handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLDLAZY);
            . . .

      results in mylibs.so being loaded twice for the current process.  On the
      other hand, given the same object and current working directory, if
      LDLIBRARYPATH=/usr/home/me/mylibs, then

            . . .
            void *handle1;
            void *handle2;

            handle1 = dlopen("mylib.so", RTLDLAZY);
            handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLDLAZY);
            . . .

      results in mylibs.so being loaded only once.

      Objects loaded by a single invocation of dlopen may import symbols from
      one another or from any object loaded automatically during program
      startup, but objects loaded by one dlopen invocation may not directly
      reference symbols from objects loaded by a different dlopen invocation.
      Those symbols may, however, be referenced indirectly using dlsym.




Page 2                                                                    10/89

dlopen(3X)      UNIX System V(C Programming Language Utilities)      dlopen(3X)


      Users who wish to gain access to the symbol table of the a.out itself
      using dlsym(0, mode) should be aware that some symbols defined in the
      a.out may not be available to the dynamic linker.  The symbol table
      created by ld for use by the dynamic linker might contain only a subset
      of the symbols defined in the a.out:  specifically those referenced by
      the shared objects with which the a.out is linked.
















































10/89                                                                    Page 3