hpux dlopen_pa man page on unix.com

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 inter-
preted 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 searches a series of directories, in the following order, for file:

o Any directories specified by the dynamic path set by calling

o Any directories specified by the environment variable

o Any directories specified by

o For ELF applications, any directories specified by a entry in the section of the original program object.

o The directories and in 32-bit mode and and in 64-bit mode.

o 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 earlier, 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
operation along with the 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 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:

Under this mode, the shared library loaded has its text segment mapped private. This can be useful for debugging.

Under this mode, only references to data symbols are relocated when the object is loaded. References to functions are not relo-
cated 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.

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 pro-
gram 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 relocation 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 invocation are made available for relocation. This ensures that all relocations are satis-
fied using symbol definitions from the same invocation.

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 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 overriding the modes, of an existing object.

Under this mode, verbose messages concerning possible unsatisfied 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 environment variable to contain the
option.

Currently, this is applicable only for PA32.

Symbols introduced into a program through calls to may be used in relocation 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 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 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, relo-
cations 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
subset 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 following 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 segment. 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 memory for the load segments.

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

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

o 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 diagnostic 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 check-
ing 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 dependencies. 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 ALSO
cc(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)

hpux man page for dlopen_pa