HP-UX Reference (11i v1 00/12) - 3 Library Functions A-M (vol 6)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

191

192

193

194

195

196

197

198

199

200

__________________________________________________________________________________________________________________________________________________________________________________________________

STANDARD Printed by: Nora Chuang [nchuang] STANDARD

/build/1111/BRICK/man3/!!!intro.3c

________________________________________________________________

___ ___

dlopen(3C) dlopen(3C)

NAME

dlopen - open a shared library

SYNOPSIS

cc [ﬂag ... ] cﬁle ... -ldl [library] ...

#include <dlfcn.h>

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

DESCRIPTION

dlopen is one 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 availableto 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 int 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.

A successful dlopen 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 pathname to the object ﬁle. If ﬁle contains a slash character, the ﬁle argument

itself is used as the pathname. Otherwise a series of directories is searched for ﬁle. First, any directories

speciﬁed by the environment variable

LD_LIBRARY_PATH

are searched. Next, any directories speciﬁed

SHLIB_PATH are searched. Then, any directories speciﬁed by a DT_RPATH entry in the .dynamic

section of the original program object are searched. Finally, the directories /usr/lib and

usr/ccs/lib in 32-bit mode and /usr/lib/pa20_64

and usr/ccs/lib/pa20_64 in 64-bit

mode are searched.

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 multiple

times in reference to the ﬁle, and even if different pathnames 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:

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 ﬁrst 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 ﬁrst 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.

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

speciﬁed the

RTLD_GLOBAL ﬂag. To determine the scope of visibility for the symbols loaded with a dlo-

pen

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 speciﬁed, the default is RTLD_LOCAL.

HP-UX Release 11i: December 2000 − 1 − Section 3−−155

___