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 appro‐
priate 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 fol‐
lowing 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 applicable 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 speci‐
fied 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 sys‐
tems, 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
argument, searches all user defined symbols (those defined by all
currently loaded shared libraries and the program to find the sym‐
bol; otherwise searches only the specified shared library. The
return value of handle will be NULL if the symbol found was gener‐
ated 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 over‐
ridden 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 ver‐
sion 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
symbols 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 con‐
stant 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 struc‐
ture to avoid symbol binding by the loader to resolve
symbol dependencies. 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 sym‐
bol and find the most visible occurrence using all sym‐
bol information sources. The value and handle fields in
the symbol return structure reflect where the most visi‐
ble 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
detachment. All explicitly loaded libraries are detached automat‐
ically 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 ref‐
erence 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 exam‐
ine 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 else‐
where 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
routine. 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 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
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 stor‐
age. 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 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.
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 sec‐
tion 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 fam‐
ily 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.
AUTHORshl_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 mod‐
ule
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)
