dlopen_pa(3C)dlopen_pa(3C)NAME
dlopen_pa: dlopen(), dlopene() - open an HP 9000 shared library; open
an HP 9000 64-bit shared library with explicit load address
SYNOPSIS
Command: [flag]... cfile... [library]...
Remarks
This manpage describes on HP 9000 systems. For on Integrity systems,
see dlopen_ia(3C).
Multithread Usage
These routines are thread-safe.
Note: The dynamic loader serializes the loading and unloading of shared
libraries in multithreaded applications using a recursive pthread mutex
lock. See the for more information.
DESCRIPTION
and are members of a family of routines that give the user direct
access to the dynamic linking facilities (using the option on the com‐
piler or command line).
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 entries
in the 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
is an extension to 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 or call returns to the process a handle which the process
may use on subsequent calls to and 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 con‐
tains a slash character, the file argument itself is used as the path
name. Otherwise searches a series of directories, in the following
order, for file:
· Any directories specified by the dynamic path set by calling
· Any directories specified by the environment variable
· Any directories specified by
· For ELF applications, any directories specified by a entry in the
section of the original program object.
· The directories and in 32-bit mode and and in 64-bit mode.
· The current working directory.
The use of is static. This means that when the program starts, the
dynamic loader uses the value in environment variable Any change to
during the program execution has no effect. The function removes this
constraint. With you can change the value (using and call to cause to
read current value. You can use this new value for subsequent library
searching.
You can use while loading shared libraries using or As described ear‐
lier, you should enable searching using the option. In case of you
should use the flag.
The following example demonstrates the function:
If the value of file is 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 all of the objects that were loaded
at program startup along with the and all objects loaded using a opera‐
tion along with the flag. As the latter set of objects can change dur‐
ing execution, the set identified by handle can also change dynami‐
cally.
Only a single copy of an object file is brought into the address space,
even if 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 reloca‐
tions take place and may have the following values:
Under this mode, the shared library loaded has its text seg‐
ment mapped private. This can be useful for debug‐
ging.
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 refer‐
ence all of the functions in any given shared
object.
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 that requires relocations against global symbols
can reference the symbols in the original any objects loaded at program
startup, from the object itself as well as any other object included in
the same invocation, and any objects that were loaded in any invocation
that specified the flag. To determine the scope of visibility for the
symbols loaded with a invocation, the mode parameter should be bitwise
or'ed with one of the following values:
The object's symbols are made available for the relocation processing
of any other object. In addition, symbol lookup
using and an associated allows objects loaded with
to be searched.
The object's symbols are made available for relocation processing only
to objects loaded in the same invocation.
If neither nor are specified, the default is
If a file is specified in multiple invocations, mode is interpreted at
each invocation. Note, however, that once has been specified, all
relocations will have been completed, rendering any further operations
redundant and any further operations irrelevant. Similarly note that
once has been specified, the object will maintain the status regardless
of any previous or future specification of so long as the object
remains in the address space (see dlclose(3C)).
To determine the scope of symbols that are made available for reloca‐
tion processing of objects loaded in a invocation, the mode parameter
can be bitwise or'ed with one of the following values:
Under this mode, the specified object, and its dependencies,
behave as if they were built with (see ld(1)).
Only symbols from objects loaded in the same invo‐
cation are made available for relocation. This
ensures that all relocations are satisfied using
symbol definitions from the same invocation.
Under this mode, only symbols from global objects and from the
object itself are available for relocation process‐
ing. It does not use symbol definitions from other
objects loaded as part of the invocation. This
flag has no effect on objects build with (see
ld(1)).
Under this mode, symbols from the object that invoked are also
made available for relocation.
The modes and are presently supported only for 64-bit applications.
The default modes for are 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:
Under this mode, the specified object and its dependencies
behave as if they were built with (see ld(1)). An
explicit unload using or returns success silently
without detaching the shared library from the
process. Subsequently, the shared library handle
is valid only for It stays invalid for and until
the next explicit load using or
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.
can be used to query the presence, or for overrid‐
ing the modes, of an existing object.
Under this mode, verbose messages concerning possible unsatis‐
fied symbols can be printed. This is equivalent to
the flag of the routine. This feature can also be
turned on for all invocations by setting the envi‐
ronment variable to contain the option.
Currently, this is applicable only for PA32.
Symbols introduced into a program through calls to may be used in relo‐
cation activities. Symbols so introduced may duplicate symbols already
defined by the program or previous operations.
To resolve the ambiguities such a situation might present, the resolu‐
tion 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 defini‐
tions 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 operation
on a file with a value dependency ordering is used by the function.
Load ordering is used in operations on the global symbol object.
When an object is first made accessible via 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 invocation or on
startup, the load and dependency order may yield different resolutions.
The symbols introduced by operations and available through 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 only a sub‐
set of externally visible symbols are typically exported: specifically
those referenced by the shared objects with which the is linked.
The exact set of exported symbols for any shared object or the can be
controlled using the linker (see ld(1)).
HP 9000 64-bit dlopene()
The dlopen_opts structure has the following members:
flags contains the load option, defined by the logical OR of the fol‐
lowing values:
Indicates that an explicit base address for the shared library
text segment is provided.
Indicates that an explicit base address for the shared library
private data segment is provided.
If this flag is set,
does not zero fill the bss part of the data seg‐
ment. This may improve load time for libraries
with large bss sections.
This flag is only valid with
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 to obtain the information needed to allocate mem‐
ory for the load segments.
The caller of 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, returns NULL. More detailed diag‐
nostic information is available through or (64-bit only).
ERRORS
If or fails, a subsequent call to returns one of the following values:
64-bit program found a 32-bit shared library.
32-bit program found a 64-bit shared library.
Not a valid library.
Invalid library: bad alignment.
Invalid library: bad machine type.
Invalid library: program header not found.
Invalid library: bad object file type.
Invalid library: bad magic number.
Invalid library: symbol table missing.
Library needs a shared fixed address but has multiple data segments.
Unknown elf version in library.
Unknown relocation type.
Cannot apply relocation in library.
Unsatisfied code symbol in library.
Unsatisfied data symbol in library.
Library needs a shared fixed address but unable to obtain it from
Invalid flags for
Cannot library because it contains TLS data.
Invalid load address for segment
only).
Shared library missing execution permission
only).
Library contains a static TLS reference to a symbol defined in a
dynamically loaded library.
Cannot open filtered library: TLS size exceeds size recorded in filter.
Internal error encountered in
I/O error mapping library.
Unable to find library.
failed for library.
failed for the library.
Out of memory.
Encounter error while loading library
only).
Non-thread-specific relocation referencing TLS symbol.
Unable to open library.
Cannot use pre-allocated address for mapping library that requires
a fixed address only).
failed on entry to or exit from dld API.
failed on exit from dld API.
failed on entry to dld API.
TPREL relocation on non-TLS symbol.
EXAMPLES
The following example illustrates the use of 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
In 64-bit mode, the environment variables and should contain a colon-
separated list of directories, in the same format as the variable (see
sh(1)). and are ignored if the process's 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)).
In 64-bit mode, with the option specified, and embedded path are
ignored while searching for dependent libraries.
Use caution when building shared libraries with external library depen‐
dencies. Any library that contains Thread Local Storage (TLS) should
not be used as a dependency. If a dependent library contains TLS, and
it is not loaded during program startup (that is, not linked against
the executable), the dynamic loader fails to perform the operation.
SEE ALSOcc(1), ld(1), sh(1), exec(2), dlclose(3C), dlerrno(3C), dlerror(3C),
dlsym(3C), dlgetfileinfo(3C), dlsetlibpath(3C).
Texts and Tutorials
(See the
option)
