|
» |
|
|
|
NAMEshl_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#include <dl.h>
shl_t shl_load(const char *path, int flags, long address);
int shl_findsym(
shl_t *handle,
const char *sym,
short type,
void *value
);
int shl_definesym(
const char *sym,
short type,
long value,
int flags
);
int shl_getsymbols(
shl_t handle,
short type,
int flags,
void *(*memory) (),
struct shl_symbol **symbols,
);
int shl_unload(shl_t handle);
int shl_get(int index, struct shl_descriptor **desc);
int shl_gethandle(shl_t handle, struct shl_descriptor **desc);
int shl_get_r(int index, struct shl_descriptor *desc);
int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc); RemarksThis manpage describes
shl*()
routines for Integrity systems.
For
shl*()
routines on PA-RISC systems, see
shl_load_pa(3X). DESCRIPTIONThese 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
-ldld
option on the command line with the
ld
command (see
ld(1)).
See
WARNINGS.
In addition, the
-E
option to the
ld
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
-b
(create shared library) option. - shl_load()
Attaches the shared library named by
path
or
the shared library name that is constructed by using the path part of
path
plus the shared library basename followed by the suffix
.0
(e.g.
/usr/lib/hpux64/libname.0)
to the process, along with all its dependent libraries.
A
.0
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
0L,
the system chooses an appropriate 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
0L.
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:
- BIND_IMMEDIATE
Resolve symbol references when the library is loaded. - BIND_DEFERRED
Delay code symbol resolution until actual reference.
Zero or more of the following can be specified by doing a bitwise
OR
operation:
- BIND_FIRST
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
BIND_TOGETHER). - BIND_NONFATAL
Default
BIND_IMMEDIATE
behavior is to treat all unsatisfied symbols as fatal.
This flag allows binding of unsatisfied code symbols
to be deferred until use. - BIND_NOSTART
Do not call the initializers for the shared library
when the library is loaded, nor on a future call to
shl_unload()
or
dlclose();
by default, all the initializers registered with the
specified library are invoked upon loading. - BIND_VERBOSE
Print verbose messages concerning possible unsatisfied symbols. - BIND_RESTRICTED
Restrict symbols visible to the library
to those present at the time the library is loaded. - DYNAMIC_PATH
Allow the loader to dynamically search for the library specified by the
path
argument.
The directories to be searched are determined by the
+s
and
+b
options of the
ld
command used when the program was linked.
This is enabled by
default if
ld +compat
was
not
specified. - BIND_TOGETHER
When used with
BIND_FIRST,
the library being mapped and its dependent
libraries will be bound together.
This is the default
behavior for all
shl_load()
requests not using
BIND_FIRST. - BIND_BREADTH_FIRST
Causes the dependent libraries to be loaded breadth first.
By default,
shl_load()
loads dependent libraries depth-first.
If successful,
shl_load()
returns a handle which can be used in subsequent calls to
shl_findsym(),
shl_unload(),
shl_gethandle(),
or
shl_gethandle_r();
otherwise
NULL
is returned.
The handle can also be used in subsequent calls to
dlclose()
or
dlsym(). 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 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 during program startup (that is, not linked against the
executable), the dynamic loader fails to perform the operation. - shl_findsym()
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
shl_load(),
or
shl_get().
You can also get
handle
from a call to
dlopen().
If a pointer to
NULL
is passed for this argument,
shl_findsym()
searches all user defined symbols (those defined by
shl_definesym()),
all currently loaded shared libraries and the program to find the symbol;
otherwise
shl_findsym()
searches only the specified shared library.
The return value of handle will be
NULL
if the symbol found was generated via
shl_definesym().
Otherwise the handle of the library where the symbol was found
is returned.
The special handle
PROG_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
TYPE_PROCEDURE,
TYPE_DATA,
or
TYPE_UNDEFINED.
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
DIAGNOSTICS
for errno settings. - shl_definesym()
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:
- TYPE_PROCEDURE
Symbol is a function. - TYPE_DATA
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.
dlsym()
will not search for any user defined symbol. - shl_getsymbols()
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
shl_definesym()
are returned.
If multiple versions of the same symbol have been defined with
shl_definesym(),
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
TYPE_PROCEDURE
and
TYPE_DATA
can be used to limit the returned symbols
to be either code or data respectively.
The
TYPE_DATA
value cause both data, storage, and tstorage symbols to be returned.
The constant
TYPE_UNDEFINED
can be used to return all symbols, regardless of type.
The
flags
argument must have one of the following values:
- IMPORT_SYMBOLS
Return symbols found on the import list. - EXPORT_SYMBOLS
Return symbols found on the export list.
All symbols defined by
shl_definesym()
are export symbols. - INITIALIZERS
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:
- NO_VALUES
Only makes sense when combined with
EXPORT_SYMBOLS
or
INITIALIZERS.
Do not calculate the value field in the return structure to avoid symbol
binding by the loader to resolve symbol dependencies.
If only a few symbol
values are needed,
shl_findsym()
can be used to find the values of interesting symbols.
This is not to be used
with
GLOBAL_VALUES. - GLOBAL_VALUES
Only makes sense when combined with
EXPORT_SYMBOLS
or
INITIALIZERS.
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
NO_VALUES.
The
memory
argument should point to a function with the same interface as
malloc()
(see
malloc(3C)). The return information consists of an array
of the following records (defined in
<dl.h>):
struct shl_symbol {
char *name,
short type,
void *value,
shl_t handle,
}; The
type
field in the return structure can have the values
TYPE_PROCEDURE,
or
TYPE_DATA.
The
value
and
handle
fields are only valid if export symbols are requested and the
NO_VALUES
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
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 handle returned from a previous call to
shl_load().
You can also get the handle from a call to
dlopen().
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 contents 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 subsequent 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 USAGEThese routines are safe to be called from multithreaded applications. DIAGNOSTICSIf 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 compatibility mode only, if
shl_findsym()
finds the indicated symbol but cannot resolve all the symbols it depends on,
errno
is set to
ENOSYM. ERRORSPossible 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. - ENOMEM
There is insufficient room in the address space to load the library. - ENOENT
The specified path does not exist, or the specified handle is invalid. - ETXTBSY
The specified shared library is currently in use and cannot be unloaded. - EACCES
Read or execute permission is denied for the specified library.
WARNINGSshl_unload()
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
free()
(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
-E
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
shl_getsymbols(),
including the name field,
become invalid once the associated library is unloaded by
shl_unload().
This is also true if a library is unloaded by a call to
dlclose(). 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 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 during program startup (that is, not linked against the
executable), the dynamic loader fails to perform the operation.
You can use
+tls=dynamic
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
WARNINGS
section 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
dl*
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 ALSOSystem Tools- ld(1)
invoke the link editor
Texts and Tutorials- HP-UX Linker and Libraries Online User Guide
(See the
+help
option to
ld(1)) - HP-UX Linker and Libraries User's Guide
(See
manuals(5)
for ordering information)
|