shl_load(3X)

NAME

shl_load(), shl_definesym(), shl_findsym(), shl_gethandle(), shl_getsymbols(), shl_unload(), shl_get(), shl_gethandle_r(), shl_get_r() − explicit load of shared libraries

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);

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 −ldld option on the command line with the cc or ld command (see cc(1) and ld(1)). 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 with the +z or +Z (position-independent code) options, 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/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. 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). This flag may not be supported in future 64-bit HP-UX releases.

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. This flag may not be supported in future 64-bit HP-UX releases.

BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to shl_unload(); by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases.

BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases.

BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases.

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 flag may not be supported in future 64-bit HP-UX releases.

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. This flag may not be supported in future 64-bit HP-UX releases.

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.

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(). If a pointer to NULL is passed for this argument, shl_findsym() searches 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, TYPE_STORAGE, or TYPE_UNDEFINED. The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by value. If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise −1 is returned.

shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the 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. This routine may not be supported in future 64-bit HP-UX releases.

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 within a library or 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, TYPE_DATA, and TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the TYPE_DATA value causes both data and storage 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. 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, TYPE_DATA, or TYPE_STORAGE, where TYPE_STORAGE is a subset of 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. This routine may not be supported in future 64-bit HP-UX releases.

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(). 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.

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() decrements the index values of all libraries having an index greater than the unloaded library. The index value −1 refers to the dynamic loader. 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. This routine may not be supported in future 64-bit HP-UX releases.

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. This routine may not be supported in future 64-bit HP-UX releases.

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(). This routine may not be supported in future 64-bit HP-UX releases.

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(). This routine may not be supported in future 64-bit HP-UX releases.

DIAGNOSTICS

If a library cannot be loaded, shl_load() returns NULL and sets errno to indicate the error. All other functions return −1 on error and set errno.

If shl_findsym() cannot find the indicated symbol, errno is set to zero. 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.

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

[ENOENT] The specified library does not exist.

[EACCES] Read or execute permission is denied for the specified library.

WARNINGS

shl_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 free(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().

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 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API.

AUTHOR

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

Museum

Related Articles

shl_load(3X)

NAME

SYNOPSIS

DESCRIPTION

DIAGNOSTICS

ERRORS

WARNINGS

AUTHOR

SEE ALSO

System Tools:

Miscellaneous:

Texts and Tutorials