shl_load(3X)

NAME

shl_load(), shl_definesym(), shl_findsym(), shl_gethandle(), shl_getsymbols(), shl_unload(), shl_get() − 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);

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 (position-independent code) option, and linking the resultant object files with the −b (create shared library) option.

shl_load() Attaches the shared library named by path to the process. 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 (see DEPENDENCIES). 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.

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 initializer for the shared library when the library is loaded, nor on a future call to shl_unload().

BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols.

If successful, shl_load() returns a handle which can be used in subsequent calls to shl_findsym(), shl_unload(), or shl_gethandle(); 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 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 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.

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 and TYPE_DATA can be used to limit the returned symbols to be either code or data respectively. 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 via shl_definesym() are export symbols.

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

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

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.

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.

If a call to shl_load() or shl_findsym() fails with ENOSYM, the process may be left in an inconsistent state. Some symbol resolutions may have occurred before the failure, and these may be invalid. The program should probably be terminated if this occurs.

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

DEPENDENCIES

Series 300/400:

shl_definesym() and shl_getsymbols() are not implemented on Series 300 and 400 systems.

When using shl_findsym(), keep in mind that the compilers place an underscore at the beginning of all external names.

Series 700/800:

The only value for the address field is 0L. Any other value is treated as if it had been specified as 0L.

The following additional values for the flags argument can be used with shl_load() on Series 700 and 800 systems:

BIND_RESTRICTED Restrict symbols visible by the library to those present at library load time.

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.

AUTHOR

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

Museum

Related Articles