shl_load_ia.3x (2010 09)

s
shl_load_ia(3X)
Integrity Systems Only
shl_load_ia(3X)
not specified. The value field contains the address of the symbol, while the handle field is the han-
dle of the library that defined the symbol, or NULL for symbols defined via the
shl_definesym()
routine and is useful in conjunction with the GLOBAL_VALUES
flag.
If successful,
shl_getsymbols()
returns the number of symbols found; otherwise it returns −1.
shl_unload()
Can be used to detach a shared library from the process. The handle argument should be the han-
dle returned from a previous call to
shl_load()
. You can also get the handle from a call to dlo-
pen(). shl_unload() 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 termination.
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).
shl_unload does not remove the
shared library from the address space until all references to that shared library have been removed.
shl_get()
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
shl_unload() or dlclose() 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 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 con-
tents of file
/usr/include/dl.h
. 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
shl_get() is static; the contents should be copied elsewhere before a subse-
quent call to the routine. The routine returns 0 normally, or −1 if an invalid index is given.
shl_gethandle()
Returns information about the library specified by the handle argument. The special handle
PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as
the one returned by the shl_get() routine. The buffer for the descriptor used by
shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to
the routine. The routine returns 0 normally, or −1 on error.
shl_get_r()
This is a reentrant version of shl_get(). The desc argument must point to a buffer of enough
user-defined storage to be filled with the library descriptor described in /usr/include/dl.h
.
Its semantics are otherwise identical to
shl_get().
shl_gethandle_r()
This is a reentrant version of shl_gethandle()
. The desc argument must point to a buffer of
enough user-defined storage to be filled with the library descriptor described in
/usr/include/dl.h
. Its semantics are otherwise identical to shl_gethandle().
MULTITHREAD USAGE
These routines are safe to be called from multithreaded applications.
DIAGNOSTICS
If a library cannot be loaded,
shl_load() returns NULL and sets errno to indicate the error. This
includes trying to shl_load() a library containing thread local storage. All other functions return −1
on error and set errno.
If
shl_findsym() cannot find the indicated symbol, errno is set to zero. On PA-RISC 32-bit compati-
bility mode only, if shl_findsym() finds the indicated symbol but cannot resolve all the symbols it
depends on, errno is set to ENOSYM.
ERRORS
Possible values for
errno include:
[ENOEXEC] The specified file is not a shared library, or a format error was detected.
[ENOSYM] Some symbol required by the shared library could not be found.
[EINVAL] The specified handle or index is not valid or an attempt was made to load a library
at an invalid address.
4 Hewlett-Packard Company − 4 − HP-UX 11i Version 3: September 2010