NAME

dlopen − open a shared object

SYNOPSIS

cc [ flag ... ] file ... −ldl [ library ... ]

#include <dlfcn.h>

void ∗dlopen(const char ∗pathname, int mode);

MT-LEVEL

MT-Safe

DESCRIPTION

dlopen() is one of a family of routines that give the user direct access to the dynamic linking facilities. (SEE Linker and Libraries Guide ).  These routines are made available via the library loaded when the option -ldl is passed to the link-editor. 

These routines are available to dynamically linked processes ONLY.

dlopen() makes a shared object available to a running process.  dlopen() returns to the process a "handle" which 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.  A path name containing an embedded ’/’ will be interpreted as an absolute path or relative to the current directory, otherwise the set of search paths currently in effect by the run-time linker will be used to locate the specified file (SEE NOTES section below).  If the value of pathname is 0, dlopen() will make 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:

RTLD_LAZY 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.  This behavior mimics the normal loading of shared object dependencies by a dynamic executable during process initialization. 

RTLD_NOW 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.

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().  However, the mode parameter may also be ored with the following value to effect the scope of symbol availability:

RTLD_GLOBAL
Under this mode, the objects symbols will be made available for all to access. 

RETURN VALUES

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

SEE ALSO

ld(1), dladdr(3X), dlclose(3X), dlerror(3X), dlsym(3X)
Linker and Libraries Guide

NOTES

If other shared objects were link edited with pathname when pathname was built (ie. the pathname has dependencies on other shared objects), those objects will automatically be loaded by dlopen().  The directory search path that will be used to find both pathname and the other needed objects may be effected by setting the environment variable LD_LIBRARY_PATH, or from a run-path setting within the application or the shared object from which the dlopen() originated.  These search rules will only be applied to pathnames that do not contain an embedded ’/’.  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 will only be loaded once into the address space of the current process. 

Users who wish to gain access to the symbol table of the a.out itself using dlopen(0, mode) should be aware that some symbols defined in the a.out may not be available to the runtime linker.  The symbol table created by ld for use by the runtime 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. 

SunOS 5.4  —  Last change: 2 Apr 1993