shl_load_ia(3X)shl_load_ia(3X)NAME
shl_load_ia: shl_load(), shl_definesym(), shl_findsym(), shl_get(),
shl_get_r(), shl_gethandle(), shl_gethandle_r(), shl_getsymbols(),
shl_unload() - explicit load of shared libraries for Integrity systems
SYNOPSIS
Remarks
This manpage describes routines for Integrity systems. For routines on
PA-RISC systems, see shl_load_pa(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). The routines themselves are
accessed by specifying the option on the command line with the command
(see ld(1)). 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.
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 and was built
with static TLS model, you cannot load it with this routine. See
"Thread Local Storage" in dld.so(5) for more information. 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 sym‐
bols.
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. 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
Causes the dependent libraries to be loaded breadth first.
By default, loads dependent libraries depth-first.
If successful, returns a handle which can be used in subsequent
calls to or otherwise NULL is returned. The handle can also be
used in subsequent calls to or
Use caution when building shared libraries with external library
dependencies. Any library that contains Thread Local Storage
(TLS) and uses static TLS model should not be used as a depen‐
dency. See "Thread Local Storage" in dld.so(5) for more informa‐
tion. If a dependent library contains TLS, was built with static
TLS model, and it is not loaded during program startup (that is,
not linked against the executable), the dynamic loader fails to
perform the operation.
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 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 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 dynami‐
cally. The type argument specifies the expected type for the sym‐
bol, and should be one of the defined constants or The latter
value suppresses type checking. 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. Val‐
ues of and can be used to limit the returned symbols to be either
code or data respectively. 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 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 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 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 automatically on process termina‐
tion.
The same shared library can be opened multiple times. 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
itself. The desc argument is used to return a pointer to a stati‐
cally allocated buffer containing a descriptor for the shared
library. The format of the descriptor is implementation depen‐
dent; to examine its format, look at the contents of file Informa‐
tion 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
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
MULTITHREAD USAGE
These routines are safe to be called from multithreaded applications.
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
compatibility mode 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)).
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 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) and uses
static TLS model should not be used as a dependency. See "Thread Local
Storage" in dld.so(5) for more information. If a dependent library
contains TLS, was built with static TLS model and it is not loaded dur‐
ing program startup (that is, not linked against the executable), the
dynamic loader fails to perform the operation. You can use compiler
option to re-compile the library to avoid errors.
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 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.
AUTHORshl_load(3X) and related functions were developed by HP.
SEE ALSO
System Tools
ld(1) invoke the link editor
Miscellaneous
dld.so(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)
Integrity Systems Onlyshl_load_ia(3X)