MirOS Manual: dladdr(3), dlclose(3), dlctl(3), dlerror(3), dlfcn(3), dlopen(3), dlsym(3)

DLFCN(3)                   BSD Programmer's Manual                    DLFCN(3)

NAME

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

SYNOPSIS

     #include <dlfcn.h>

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

     int
     dlclose(void *handle);

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

     int
     dladdr(const void *addr, Dl_info *info);

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

     const 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 a process's address space
     under program control.

     The dlopen() function takes a name of a shared object as its first argu-
     ment. 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.

     The path argument can either be an absolute pathname or it can be of the
     form "lib<name>.so[.xx[.yy]]" in which case the same library search rules
     apply that are used for "intrinsic" shared library searches. A null
     pointer supplied for path is interpreted as a reference to the main exe-
     cutable of the process. The second argument currently has no effect, but
     should be set to DL_LAZY for future compatibility.

     dlopen() returns a handle to be used in calls to dlclose(), dlsym(), 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 once loaded at startup time) the object is
     removed when its reference count drops to zero.

     dlsym() looks for a definition of symbol in the shared object designated
     by handle. The symbol's address is returned. If the symbol cannot be
     resolved, NULL is returned.

     If dlsym() is called with the special handle NULL, it is interpreted as a
     reference to the executable or shared object from which the call is being
     made. Thus a shared object can reference its own symbols.

     If dlsym() is called with the special handle RTLD_DEFAULT, all the shared
     objects will be searched in the order they were loaded.

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

     If dlsym() is called with the special handle RTLD_SELF, then the search
     for the symbol is limited to the shared object issuing the call to
     dlsym() and those shared objects which were loaded after it.

     dladdr() queries the dynamic linker for information about the shared ob-
     ject containing the address addr. The information is returned in the
     structure specified by info. The structure contains at least the follow-
     ing members:

     const char *dli_fname     The pathname of the shared object containing
                               the address addr.

     void *dli_fbase           The base address at which the shared object is
                               mapped into the address space of the calling
                               process.

     const char *dli_sname     The name of the nearest run-time symbol with a
                               address less than or equal to addr.

                               If no symbol with a suitable address is found,
                               both this field and dli_saddr are set to NULL.

     void *dli_saddr           The address of the symbol returned in
                               dli_sname.

     If a mapped shared object containing addr cannot be found, dladdr() re-
     turns 0. In that case, a message detailing the failure can be retrieved
     by calling dlerror(). On success, a non-zero value is returned. 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 as-
     pects 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.

SEE ALSO

     ld(1), ld.so(1), link(5)

HISTORY

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

BUGS

     An error that occurs while processing a dlopen() request results in the
     termination of the program.

MirOS BSD #10-current         September 30, 1995                             1

Generated on 2014-04-02 20:57:59 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.