Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > D

dlopen_ia(3C)

Integrity Systems Only
HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

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.

SEE ALSO

cc(1), ld(1), sh(1), exec(2), dlclose(3C), dlerrno(3C), dlerror(3C), dlgetfileinfo(3C), dlsetlibpath(3C), dlsym(3C).

Texts and Tutorials

HP-UX Linker and Libraries Online User Guide

(See the +help option)

HP-UX Linker and Libraries User's Guide

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.