hpux dld_getenv man page on unix.com

shl_load_pa(3X) shl_load_pa(3X)

NAME
shl_load_pa: shl_load(), shl_definesym(), shl_findsym(), shl_get(), shl_get_r(), shl_gethandle(), shl_gethandle_r(), shl_getsymbols(),
shl_unload(), dld_getenv() - explicit load of shared libraries for PA-RISC systems

SYNOPSIS
Remarks
This manpage describes routines on PA-RISC systems. For routines on Integrity systems, see shl_load_ia(3X).

DESCRIPTION
These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the
addresses of symbols defined within them). On PA-RISC 32-bit systems, the routines themselves are accessed by specifying the option on the
command line with the or command (see cc(1) and ld(1)). On PA-RISC 64-bit systems, the routines are accessed by specifying either or on
the command line. See In addition, the option to the command can be used to ensure that all symbols defined in the program are available
to the loaded libraries. This is the default behavior on PA-RISC 64-bit systems.

Shared libraries are created by compiling source files and linking the resultant object files with the (create shared library) option.

Attaches the shared library named by
path the shared library name that is constructed by using the path part of path plus the shared library basename followed by the suf-
fix (e.g. to the process, along with all its dependent libraries. A version is looked for first for those shared libraries that do
not have internal names. See ld(1)). The library is mapped at the specified address. If address is the system chooses an appropri-
ate address for the library. This is the recommended practice because the system has the most complete knowledge of the address
space; currently, the address field is ignored, and assumed to be If the shared library contains thread local storage, you cannot load
it with this routine.

The flags argument is made up of several fields. One of the following must be specified:

Resolve symbol references when the library is loaded.

Delay code symbol resolution until actual reference.

Zero or more of the following can be specified by doing a bitwise OR operation:

Place the library at the head of the symbol search order.
In default mode, the library and its dependent libraries are bound independently of each other (see

Default
behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred
until use.

Do not call the initializers for the shared library
when the library is loaded, nor on a future call to or by default, all the initializers registered with the specified
library are invoked upon loading.

Print verbose messages concerning possible unsatisfied
symbols. This feature can also be turned on for all invocations by setting to contain option. Currently, this is applica-
ble only for PA32.

Restrict symbols visible to the library
to those present at the time the library is loaded.

Allow the loader to dynamically search for the library specified by the
path argument. The directories to be searched are determined by the and options of the command used when the program was
linked. On PA-RISC 64-bit systems, this is enabled by default if was not specified.

When used with
the library being mapped and its dependent libraries will be bound together. This is the default behavior for all requests
not using

(64-bitmodeonly:)
Causes the dependent libraries to be loaded breadth first. By default, the 64-bit mode loads dependent libraries depth-
first.

If successful, returns a handle which can be used in subsequent calls to or otherwise NULL is returned. On PA-RISC 64-bit systems,
the handle can also be used in subsequent calls to or

Obtains the address of an exported symbol
sym from a shared library. The handle argument should be a pointer to the handle of a loaded shared library that was returned from a
previous call to or On PA-RISC 64-bit systems, you can also get handle from a call to If a pointer to NULL is passed for this argu-
ment, searches all user defined symbols (those defined by all currently loaded shared libraries and the program to find the symbol;
otherwise searches only the specified shared library. The return value of handle will be NULL if the symbol found was generated via
Otherwise the handle of the library where the symbol was found is returned. The special handle can be used to refer to the program
itself, so that symbols exported from the program can also be accessed dynamically.

The type argument specifies the expected type for the symbol, and should be one of the defined constants or The latter value sup-
presses type checking. These are the only accepted type arguments on PA-RISC 64-bit systems. On PA-RISC 32i-bit systems, you can
also specify or

The address of the symbol is returned in the variable pointed to by value. If the symbol is a thread local storage symbol, the
address of the symbol is the value of the thread pointer + the starting address of the shared library + the offset of the symbol in
the library.

This routine returns 0 if successful; otherwise -1 is returned. See for errno settings.

Adds a symbol to the user hash table for the current process.
If value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated
library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library
that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed.

Possible symbol types include:

Symbol is a function.

Symbol is data.

Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of
this flag. You cannot use this routine to define a thread local storage symbol. will not search for any user defined symbol.

Provides an array of symbol records,
allocated using the supplied memory allocator, that are associated with the library specified by handle. If the handle argument is a
pointer to NULL, symbols defined using are returned. If multiple versions of the same symbol have been defined with only the version
from the specified symbol information source that would be considered for symbol binding is returned.

The type argument is used to restrict the return information to a specific type. Values of and can be used to limit the returned sym-
bols to be either code or data respectively. On PA-RISC 32i-bit systems, you can also specify a type of or The value cause both data,
storage, and tstorage symbols to be returned. The constant can be used to return all symbols, regardless of type.

The flags argument must have one of the following values:

Return symbols found on the import list.

Return symbols found on the export list.
All symbols defined by are export symbols.

Return symbols that are specified as the initializers of the library.

Zero or more of the following can be specified by doing a bitwise OR operation:

Only makes sense when combined with
or Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol depen-
dencies. If only a few symbol values are needed, can be used to find the values of interesting symbols. This is not to be
used with

Only makes sense when combined with
or Use the name and type information of each return symbol and find the most visible occurrence using all symbol information
sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found.
Not to be used with

The memory argument should point to a function with the same interface as (see malloc(3C)).

The return information consists of an array of the following records (defined in

The type field in the return structure can have the values or On PA-RISC 32i-bit systems, you can also have the values or These are a
subset of The value and handle fields are only valid if export symbols are requested and the flag is not specified. The value field
contains the address of the symbol, while the handle field is the handle of the library that defined the symbol, or NULL for symbols
defined via the routine and is useful in conjunction with the flag.

If successful, returns the number of symbols found; otherwise it returns -1.

Can be used to detach a shared library from the process.
The handle argument should be the handle returned from a previous call to On PA-RISC 64-bit systems, you can also get the handle from
a call to returns 0 if successful; otherwise -1 is returned. Any initializers registered with the library are called before detach-
ment. All explicitly loaded libraries are detached automatically on process termination.

The same shared library can be opened multiple times. On PA-RISC 32-bit systems, unloads the shared library regardless of whether
there are other references to it through other load invocations or through implicit references from other shared libraries. No refer-
ence count is kept. On PA-RISC 64-bit systems, a reference counter is kept for each loaded shared library, like the behavior of
dlopen(3C) and dlclose(3C). does not remove the shared library from the address space until all references to that shared library
have been removed.

Returns information about currently loaded libraries,
including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared
library search list for the process. A subsequent call to or decrements the index values of all libraries having an index greater
than the unloaded library. The index value -1 refers to the dynamic loader and the index value -2 refers to the program file itself.

The desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The
format of the descriptor is implementation dependent; to examine its format, look at the contents of file Information common to all
implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor
used by is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally,
or -1 if an invalid index is given.

Returns information about the library specified by the handle argument.
The special handle can be used to refer to the program itself. The descriptor returned is the same as the one returned by the rou-
tine. The buffer for the descriptor used by is static; the contents should be copied elsewhere before a subsequent call to the rou-
tine. The routine returns 0 normally, or -1 on error.

This is a reentrant version of
The desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in Its
semantics are otherwise identical to

Informs the dynamic loader that the environment variable
has been modified since program startup and the new value should be used for subsequent calls to

MULTITHREAD USAGE
These routines are safe to be called from multithreaded applications.

Note: The 32-bit dynamic loader serializes the loading and unloading of shared libraries in multithreaded applications using a pthread
mutex lock. See the for more information.

DIAGNOSTICS
If a library cannot be loaded, returns NULL and sets to indicate the error. This includes trying to a library containing thread local
storage. All other functions return -1 on error and set

If cannot find the indicated symbol, is set to zero. On PA-RISC 32-bit systems only, if finds the indicated symbol but cannot resolve all
the symbols it depends on, is set to

ERRORS
Possible values for include:

The specified file is not a shared library, or a format error was detected.

Some symbol required by the shared library could not be found.

The specified handle or index is not valid
or an attempt was made to load a library at an invalid address.

There is insufficient room in the address space to load the library.

The specified path does not exist, or the specified handle is invalid.

The specified shared library is currently in use and cannot be unloaded.

Read or execute permission is denied for the specified library.

WARNINGS
detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the
library. In this respect, an unloaded shared library is much like a block of memory deallocated via (see malloc(3C)).

On PA-RISC 32-bit systems, unloads the shared library regardless of whether there are other references to it. On PA-RISC 64-bit systems, a
reference count is kept for each loaded library, and does not remove the shared library until all references are removed.

Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported
by a shared library seen at link time). Therefore the option to ld(1) should be used when using these routines if the loaded libraries are
to refer to program symbols.

All symbol information returned by including the name field, become invalid once the associated library is unloaded by On PA-RISC 64-bit
systems, this is also true if a library is unloaded by a call to

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.

When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the section
in dld.sl(5) for further details.

Future HP-UX 64-bit environments may not support these routines and flags or may only support a subset of them. Instead, they will use the
SVR4 dynamic loading API. Users are encouraged to migrate to the family of dynamic linking routines. See the dlclose(3C), dlerror(3C),
dlget(3C), dlgetname(3C), dlmodinfo(3C), dlopen(3C), and dlsym(3C) man pages for more information.

AUTHOR
shl_load(3X) and related functions were developed by HP.

SEE ALSO
System Tools
ld(1) invoke the link editor

Miscellaneous
dld.sl(5) dynamic loader
dlclose(3C) unload a shared library previously loaded by
dlerror(3C) print the last error message recorded by
dlget(3C) return information about a loaded module
dlgetname(3C) return the name of the storage containing a load module
dlmodinfo(3C) return information about a loaded module
dlopen(3C) load a shared library
dlsym(3C) get the address of a symbol in a shared library

Texts and Tutorials
(See the option to ld(1))

(See manuals(5) for ordering information)

PA-RISC Systems Only shl_load_pa(3X)

hpux man page for dld_getenv