DLFCN(3)                NetBSD Library Functions Manual               DLFCN(3)

NAME
     dlopen, dlclose, dlsym, dlvsym, dladdr, dlctl, dlerror -- dynamic link
     interface

LIBRARY
     (These functions are not in a library.  They are included in every dynam-
     ically linked program automatically.)

SYNOPSIS
     #include <dlfcn.h>

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

     int
     dlclose(void *handle);

     void *
     dlsym(void * restrict handle, const char * restrict symbol);

     void *
     dlvsym(void * restrict handle, const char * restrict symbol,
         const char *version);

     int
     dladdr(void * restrict addr, Dl_info * restrict dli);

     int
     dlctl(void *handle, int cmd, void *data);

     char *
     dlerror(void);

DESCRIPTION
     These functions provide an interface to the run-time linker ld.so(1).
     They allow new shared objects to be loaded into the process' address
     space under program control.

     The dlopen() function takes the name of a shared object as the first
     argument.  The path argument can be specified as either an absolute path-
     name to a shared object or just the name of the shared object itself.
     When an absolute pathname is specified, only the path provided will be
     searched.  When just a shared object name is specified, the same search
     rules apply that are used for ``intrinsic'' shared object searches.  (see
     ld.elf_so(1))

     Shared libraries take the following form: ``lib<name>.so[.xx[.yy]]''.

     The shared object is mapped into the address space, relocated, and its
     external references are resolved in the same way as is done with the
     implicitly loaded shared libraries at program startup.

     If the first argument is NULL, dlopen() returns a handle on the global
     symbol object.  This object provides access to all symbols from an
     ordered set of objects consisting of the original program image and any
     dependencies loaded during startup.

     The mode parameter specifies symbol resolution time and symbol visibil-
     ity.  One of the following values may be used to specify symbol resolu-
     tion time:

           RTLD_NOW       Symbols are resolved immediately.

           RTLD_LAZY      Symbols are resolved when they are first referred
                          to.  This is the default value if resolution time is
                          unspecified.

     One of the following values may be used to specify symbol visibility:

           RTLD_GLOBAL    The object's symbols and the symbols of its depen-
                          dencies will be visible to other objects.

           RTLD_LOCAL     The object's symbols and the symbols of its depen-
                          dencies will not be visible to other objects.  This
                          is the default value if visibility is unspecified.

     To specify both resolution time and visibility, bitwise inclusive OR one
     of each of the above values together.  If an object was opened with
     RTLD_LOCAL and later opened with RTLD_GLOBAL, then it is promoted to
     RTLD_GLOBAL.

     Additionally, one of the following flags may be ORed into the mode argu-
     ment:

           RTLD_NODELETE    Prevents unload of the loaded object on dlclose().
                            The same behaviour may be requested by -z nodelete
                            option of the static linker ld(1).

           RTLD_NOLOAD      Only return valid handle for the object if it is
                            already loaded in the process address space, oth-
                            erwise do not load the object and return NULL.

     dlopen() returns a handle to be used in calls to dlclose(), dlsym(),
     dlvsym(), and dlctl().  If the named shared object has already been
     loaded by a previous call to dlopen() (and not yet unloaded by
     dlclose()), a handle referring to the resident copy is returned.

     dlclose() unlinks and removes the object referred to by handle from the
     process address space.  If multiple calls to dlopen() have been done on
     this object, or the object was one loaded at startup time, or the object
     is a dependency of another object then the object is removed when its
     reference count drops to zero.  dlclose() returns 0 on success and non-
     zero on failure.

     dlsym() looks for a definition of symbol in the shared object designated
     by handle, and all shared objects that are listed as dependencies.  The
     symbol's address is returned.  If the symbol cannot be resolved, NULL is
     returned.

     dlsym() may also be called with special handle values.  dlsym() respects
     symbol visibility as specified by the dlopen() mode parameter.  However,
     the symbols of an object's dependencies are always visible to it.  All
     shared objects loaded at program startup are globally visible.  Only the
     symbols in the main executable that are referenced by a shared object at
     link time will be visible unless it has been linked with the --export-
     dynamic option where all of its symbols will be visible.  The following
     special handle values may be used with dlsym():

           NULL            Interpreted as a reference to the executable or
                           shared object from which the call is being made.
                           Thus an object can reference its own symbols and
                           the symbols of its dependencies without calling
                           dlopen().

           RTLD_DEFAULT    All the visible shared objects and the executable
                           will be searched in the order they were loaded.

           RTLD_NEXT       The search for symbol is limited to the visible
                           shared objects which were loaded after the one
                           issuing the call to dlsym().  Thus, if dlsym() is
                           called from the main program, all the visible
                           shared libraries are searched.  If it is called
                           from a shared library, all subsequently visible
                           shared libraries are searched.

           RTLD_SELF       The search for symbol is limited to the shared
                           object issuing the call to dlsym() and those shared
                           objects which were loaded after it that are visi-
                           ble.

     dlvsym() does the same as dlsym() but takes a version string as an addi-
     tional argument.  Both the symbol and the version must match in order for
     the symbol to be resolved.

     dladdr() examines all currently mapped shared objects for a symbol whose
     address -- as mapped in the process address space -- is closest to but
     not exceeding the value passed in the first argument addr.  The symbols
     of a shared object are only eligible if addr is between the base address
     of the shared object and the value of the symbol ``_end'' in the same
     shared object.  If no object for which this condition holds true can be
     found, dladdr() will return 0.  Otherwise, a non-zero value is returned
     and the dli argument will be used to provide information on the selected
     symbol and the shared object it is contained in.  The dli argument points
     at a caller-provided Dl_info structure defined as follows:

           typedef struct {
                   const char  *dli_fname;     /* File defining the symbol */
                   void        *dli_fbase;     /* Base address */
                   const char  *dli_sname;     /* Symbol name */
                   const void  *dli_saddr;     /* Symbol address */
           } Dl_info;

     The structure members are further described as follows:

     dli_fname    The pathname of the shared object containing the address
                  addr.

     dli_fbase    The base address at which this shared object is loaded in
                  the process address space.  This may be zero if the symbol
                  was found in the internally generated ``copy'' section (see
                  link(5)) which is not associated with a file.

     dli_sname    points at the nul-terminated name of the selected symbol

     dli_saddr    is the actual address (as it appears in the process address
                  space) of the symbol.

     Note: both strings pointed at by dli_fname and dli_sname reside in memory
     private to the run-time linker module and should not be modified by the
     caller.

     In dynamically linked programs, the address of a global function will
     point to its program linkage table entry, rather than to the entry point
     of the function itself.  This causes most global functions to appear to
     be defined within the main executable, rather than in the shared
     libraries where the actual code resides.

     dlctl() provides an interface similar to ioctl(2) to control several
     aspects of the run-time linker's operation.  This interface is currently
     under development.

     dlerror() returns a character string representing the most recent error
     that has occurred while processing one of the other functions described
     here.  If no dynamic linking errors have occurred since the last invoca-
     tion of dlerror(), dlerror() returns NULL.  Thus, invoking dlerror() a
     second time, immediately following a prior invocation, will result in
     NULL being returned.

ERRORS
     The error ``Cannot dlopen non-loadable /usr/lib/libpthread.so.1'' is gen-
     erated when a program dlopen()s a module that needs libpthread but isn't
     linked against it itself.

SEE ALSO
     ld(1), rtld(1), link(5)

HISTORY
     Some of the dl* functions first appeared in SunOS 4.

NetBSD 6.0                       June 25, 2011                      NetBSD 6.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen