dlopen_ia.3c (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

dlopen_ia(3C) dlopen_ia(3C)

(Integrity Systems Only)

NAME

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

SYNOPSIS

Command:

cc [ﬂag]... cﬁle...

-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 speciﬁed by a ﬁle available to a running process. A shared object may

specify other objects that it "needs" in order to execute properly. These dependencies are speciﬁed 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.

ﬁle is used to construct a path name to the object ﬁle. If ﬁle contains a slash character, the ﬁle argument

itself is used as the path name. Otherwise

dlopen() searches a series of directories, in the following

order, for ﬁle :

• Any directories speciﬁed by the dynamic path set by calling

dlsetlibpath()

• Any directories speciﬁed by the environment variable

LD_LIBRARY_PATH

• Any directories speciﬁed by

SHLIB_PATH.

• Any directories speciﬁed 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 ﬁle 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 ﬂag. As the latter set of objects can change during execution,

the set identiﬁed by handle can also change dynamically.

Only a single copy of an object ﬁle is brought into the address space, even if

dlopen() is invoked multi-

ple times in reference to the ﬁle, and even if different path names are used to reference the ﬁle.

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:

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (6 pages)

PAGE 1
dlopen_ia(3C) dlopen_ia(3C) (Integrity Systems Only) NAME dlopen_ia: dlopen(), dlopene() - open a shared library on Integrity systems SYNOPSIS Command: cc [flag]... cfile ... -ldl [library ]... #include 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.
PAGE 2
dlopen_ia(3C) dlopen_ia(3C) (Integrity Systems Only) RTLD_TEXT_PRIVATE Under this mode, the shared library loaded has its text segment mapped private. This can be useful for debugging. A 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.
PAGE 3
dlopen_ia(3C) dlopen_ia(3C) (Integrity Systems Only) 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.
PAGE 4
dlopen_ia(3C) dlopen_ia(3C) (Integrity Systems Only) 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().
PAGE 5
dlopen_ia(3C) dlopen_ia(3C) (Integrity Systems Only) [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.
PAGE 6
dlopen_ia(3C) dlopen_ia(3C) (Integrity Systems Only) /* 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)).