dlopen_ia(3C)

NAME

dlopen_ia: dlopen(), dlopene() — open a shared library on Integrity systems

SYNOPSIS

Command: cc [flag]... cfile... -ldl [library]...

#include <dlfcn.h>

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

void *dlopene(const char *file, int mode, struct dlopen_opts *opts);

Remarks

This manpage describes dlopen() on Integrity systems. For dlopen() on HP 9000 systems, see dlopen_pa(3C).

Multithread Usage

These routines are thread-safe.

Note: The dynamic loader dld.so serializes the loading and unloading of shared libraries in multithreaded applications using a recursive pthread mutex lock. See the HP-UX Linker and Libraries Online User Guide for more information.

DESCRIPTION

dlopen() and dlopene() are members of a family of routines that give the user direct access to the dynamic linking facilities (using the -ldl option on the compiler or ld command line).

dlopen() makes a shared object specified by a file available to a running process. A shared object may specify other objects that it "needs" in order to execute properly. These dependencies are specified by DT_NEEDED entries in the .dynamic section of the original object. Each needed object may, in turn, specify other needed objects. All such objects are loaded along with the original object as a result of the call to dlopen().

dlopene() is an extension to dlopen() which allows the caller to specify explicitly the placement of a shared library's text and data segment when the library is dynamically loaded.

A successful dlopen() or dlopene() call 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.

file is used to construct a path name to the object file. If file contains a slash character, the file argument itself is used as the path name. Otherwise dlopen() searches a series of directories, in the following order, for file:

Any directories specified by the dynamic path set by calling dlsetlibpath().
Any directories specified by the environment variable LD_LIBRARY_PATH.
Any directories specified by SHLIB_PATH.
Any directories specified by a DT_RPATH entry in the .dynamic section of the original program object.
The directories /usr/lib/hpux32 in 32-bit mode and /usr/lib/hpux64 in 64-bit mode.
The current working directory.

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 a.out, all of the objects that were loaded at program startup along with the a.out, and all objects loaded using a dlopen() operation along with the RTLD_GLOBAL flag. As the latter set of objects can change during execution, the set identified by 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, and even if different path names are used to reference the file.

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_TEXT_PRIVATE: Under this mode, the shared library loaded has its text segment mapped private. This can be useful for debugging.
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.
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 are available.

Any object loaded by dlopen() that requires relocations against global symbols can reference the symbols in the original a.out, any objects loaded at program startup, from the object itself as well as any other object included in the same dlopen() invocation, and any objects that were loaded in any dlopen() invocation that 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 or'ed with one of the following values:

RTLD_GLOBAL: 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 RTLD_GLOBAL to be searched.
RTLD_LOCAL: The object's symbols are made available for relocation processing only to objects loaded in the same dlopen() invocation.

If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, the default is RTLD_LOCAL.

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, rendering any further RTLD_NOW operations redundant and any further RTLD_LAZY operations irrelevant.

Similarly, 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(3C)).

To determine the scope of symbols that are made available for relocation processing of objects loaded in a dlopen() invocation, the mode parameter can be bitwise or'ed with one of the following values:

RTLD_GROUP: Under this mode, the specified object, and its dependencies, behave as if they were built with -B group (see ld(1)). Only symbols from objects loaded in the same dlopen() invocation are made available for relocation. This ensures that all relocations are satisfied using symbol definitions from the same dlopen() invocation.
RTLD_WORLD: Under this mode, only symbols from global objects and from the object itself are available for relocation processing. It does not use symbol definitions from other objects loaded as part of the dlopen() invocation. This flag has no effect on objects build with -B group (see ld(1)).
RTLD_PARENT: Under this mode, symbols from the object that invoked dlopen() are also made available for relocation.

The default modes for dlopen() are RTLD_WORLD|RTLD_GROUP. These flags are OR'ed together when the same object is loaded with different modes.

The following flags do not affect relocation processing but provide other features:

RTLD_NODELETE: Under this mode, the specified object and its dependencies behave as if they were built with -B nodelete (see ld(1)). An explicit unload using dlclose() or shl_load() returns success silently without detaching the shared library from the process. Subsequently, the shared library handle is valid only for shl_findsym(). It stays invalid for dlsym(), dlclose(), and shl_unload() until the next explicit load using shl_load() or dlclose().
RTLD_NOLOAD: Under this mode, the specified object is not loaded into the process's address space, but a valid handle is returned if the object already exists in the process address space. If the specified object does not already exist, then an error is returned. RTLD_NOLOAD can be used to query the presence, or for overriding the modes, of an existing object.

Symbols introduced into a program through 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 a symbol definition is based on a symbol resolution order.

Two such resolution orders are defined: load and dependency ordering.

Load order establishes an ordering among symbol definitions using the temporal order in which the objects containing the definitions were loaded, such that the definition first loaded has priority over definitions added later. 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 via a dlopen() operation on a file with a value 0, dependency ordering is used by the dlsym() function. Load ordering is used in dlsym() operations on the global symbol object.

When an object is first made accessible via dlopen(), it and its dependent objects are added in dependency order. Once all objects are added, relocations are performed using load order. Note that if an object and its dependencies have been loaded by a previous dlopen() invocation or on startup, the load and dependency order may yield different resolutions.

The symbols introduced by dlopen() operations and available through dlsym() are those which are "exported" as symbols of global scope by the object. For shared objects, such symbols are typically those that were specified in (for example) C source code as having extern linkage. For a.out's, only a subset of externally visible symbols are typically exported: specifically those referenced by the shared objects with which the a.out is linked.

The exact set of exported symbols for any shared object or the a.out can be controlled using the linker (see ld(1)).

The dlopen_opts structure has the following members:

struct dlopen_opts { 
long flags; 
char* text_addr; 
char* data_addr; 
}; 

flags contains the load option, defined by logical OR of the following values:

RTLD_EXT_TEXT_ADDR: Indicates that an explicit base address for the shared library text segment is provided.
RTLD_EXT_DATA_ADDR: Indicates that an explicit base address for the shared library private data segment is provided.
RTLD_EXT_DATA_NO_ZERO_FILL: If this flag is set, dlopene() does not zero fill the bss part of the data segment. This may improve load time for libraries with large bss sections. This flag is only valid with RTLD_EXT_DATA_ADDR.

The dynamic loader only accesses the address fields that are specified by the flags fields.

text_addr contains the explicit base address for the shared library's text segment.

data_addr contains the explicit base address for the shared library's data segment.

Both the text_addr and data_addr must be aligned at a 16-byte boundary.

The caller can invoke dlgetfileinfo() to obtain the information needed to allocate memory for the load segments.

The caller of dlopene() is responsible for allocating memory with the appropriate permission:

READ, WRITE and EXECUTE (RWX) permission for text_addr.
READ and WRITE (RW) permission for data_addr.

RETURN VALUE

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

ERRORS

If dlopen() or dlopene() fails, a subsequent call to dlerrno() returns one of the following values:

RTLD_ERR_ARCH_EXT_NOT_SUPPORTED: Cannot load library because required extensions not present in the hardware.
RTLD_ERR_BAD_ABI1: 64-bit program found a 32-bit shared library.
RTLD_ERR_BAD_ABI2: 32-bit program found a 64-bit shared library.
RTLD_ERR_BAD_DLL: Not a valid library.
RTLD_ERR_BAD_DLL_ALIGNMENT: Invalid library: bad alignment.
RTLD_ERR_BAD_DLL_BAD_MACHINE: Invalid library: bad machine type.
RTLD_ERR_BAD_DLL_BAD_OBJFILE: Invalid library: bad object file type.
RTLD_ERR_BAD_DLL_BAD_PHDR: Invalid library: program header not found.
RTLD_ERR_BAD_DLL_MAGIC_NUM: Invalid library: bad magic number.
RTLD_ERR_BAD_DLL_NO_SYMTAB: Invalid library: symbol table missing.
RTLD_ERR_BAD_DLL_SEGMENT_COUNT: Library needs a shared fixed address but has multiple data segments.
RTLD_ERR_BAD_ELF_VER: Unknown elf version in library.
RTLD_ERR_BAD_RELOC: Unknown relocation type.
RTLD_ERR_CANT_APPLY_RELOC: Cannot apply relocation in library.
RTLD_ERR_CODE_UNSAT: Unsatisfied code symbol in library.
RTLD_ERR_DATA_UNSAT: Unsatisfied data symbol in library.
RTLD_ERR_DLDD_COMM_FAILURE: Library needs a shared fixed address but unable to obtain it from dldd.
RTLD_ERR_DLOPEN_BAD_FLAGS: Invalid flags for dlopen().
RTLD_ERR_DLOPEN_TLS_LIB: Cannot dlopen() library because it contains TLS data.
RTLD_ERR_DLOPENE_BAD_ADDR: Invalid load address for segment (dlopene() only).
RTLD_ERR_DLOPENE_NO_EXEC_PERM: Shared library missing execution permission (dlopene() only).
RTLD_ERR_DYN_FILTER_STLS_REF: Library contains a static TLS reference to a symbol defined in a dynamically loaded library.
RTLD_ERR_FILTER_TLS: Cannot open filtered library: TLS size exceeds size recorded in filter.
RTLD_ERR_INTERNAL_ERROR: Internal error encountered in dld.
RTLD_ERR_IO: I/O error mapping library.
RTLD_ERR_LIB_OPEN: Unable to find library.
RTLD_ERR_MMAP_FAILED: mmap() failed for library.
RTLD_ERR_MPROTECT_FAILED: mprotect() failed for the library.
RTLD_ERR_NO_MEMORY: Out of memory.
RTLD_ERR_NOMMAP_FAILED: Encounter error while loading library (dlopene() only).
RTLD_ERR_NON_TLS_RELOC_TO_TLS_SYM: Non-thread-specific relocation referencing TLS symbol.
RTLD_ERR_OPEN: Unable to open library.
RTLD_ERR_PREALLOC_ADDR_NOT_USE: Cannot use pre-allocated address for mapping library that requires a fixed address (dlopene() only).
RTLD_ERR_SETCANCELSTATE_FAILED: __thread_setcancelstate failed on entry to or exit from dld API.
RTLD_ERR_SIGENABLE_FAILED: sigenable failed on exit from dld API.
RTLD_ERR_SIGINHIBIT_FAILED: siginhibit failed on entry to dld API.
RTLD_ERR_TPREL_NON_TLS_SYM: TPREL relocation on non-TLS symbol.

EXAMPLES

The following example illustrates the use of dlopene() to load a shared library with an explicit data segment address. For simplicity, error checking has been omitted.

#include <dlfcn.h>
#include <sys/mman.h>

int main() {
    struct dlfileinfo info;
    void *handle;
    struct dlopen_opts opts;
    int status;

    memset(&info, 0, sizeof(info));
    memset(&opts, 0, sizeof(opts));

    /* Get file info */
    status = dlgetfileinfo("libfoo.so", sizeof(info), &info);

    opts.flags = RTLD_EXT_DATA_ADDR;
    /* allocate memory for the data segment */
    opts.data_addr = (char*) mmap(0, info.data_size,
                                PROT_READ|PROT_WRITE,
                                MAP_SHARED|MAP_ANONYMOUS,
                                -1, 0);

    /* call dlopene */
    handle = dlopene("libfoo.so", RTLD_NOW|RTLD_GLOBAL, &opts);

    /* Insert user code to use library */

    /* close library */
    status = dlclose(handle);

    /* free memory */
    munmap(opts.data_addr, info.data_size);
}

WARNINGS

The environment variable LD_LIBRARY_PATH and SHLIB_PATH should contain a colon-separated list of directories, in the same format as the PATH variable (see sh(1)). LD_LIBRARY_PATH and SHLIB_PATH are ignored if the process' real user id is different from its effective user id or its real group id is different from its effective group id (see exec(2)).

With the +compat option specified, LD_LIBRARY_PATH and +b embedded path are ignored while searching for dependent libraries.

Use caution when building shared libraries with external library dependencies. Any library that contains Thread Local Storage (TLS) and uses static TLS model should not be used as a dependency. See Thread Local Storage in dld.so(5) for more information.

If a dependent library contains TLS, was built with static TLS model, and was not loaded during program startup (that is, not linked against the executable), the dynamic loader fails to perform the operation. You can use +tls=dynamic compiler option to re-compile the library to avoid errors.

dlopen_ia(3C)

Technical documentation

» Table of Contents

» Index