shl_load_pa(3X)

NAME

shl_load_pa: shl_load(), shl_definesym(), shl_findsym(), shl_get(), shl_get_r(), shl_gethandle(), shl_gethandle_r(), shl_getsymbols(), shl_unload(), dld_getenv() — explicit load of shared libraries for PA-RISC 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); 

void dld_getenv(); 

Remarks

This manpage describes shl*() routines on PA-RISC systems. For shl*() routines on Integrity systems, see shl_load_ia(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). On PA-RISC 32-bit systems, 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)). On PA-RISC 64-bit systems, the routines are accessed by specifying either -ldld or -ldl on the command line. 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. This is the default behavior on PA-RISC 64-bit systems.

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/pa20_64/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, you cannot load it with this routine. 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. On PA-RISC 64-bit systems, 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: (64-bitmodeonly:) Causes the dependent libraries to be loaded breadth first. By default, the 64-bit mode 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. On PA-RISC 64-bit systems, the handle can also be used in subsequent calls to dlclose() or dlsym().

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(). On PA-RISC 64-bit systems, 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. These are the only accepted type arguments on PA-RISC 64-bit systems. On PA-RISC 32i-bit systems, you can also specify TYPE_STORAGE, or TYPE_TSTORAGE. 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. On PA-RISC 32i-bit systems, you can also specify a type of TYPE_STORAGE or TYPE_TSTORAGE. 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. On PA-RISC 32i-bit systems, you can also have the values TYPE_STORAGE or TYPE_TSTORAGE. These are 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(). On PA-RISC 64-bit systems, 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. On PA-RISC 32-bit systems, shl_unload unloads the shared library regardless of whether there are other references to it through other load invocations or through implicit references from other shared libraries. No reference count is kept. On PA-RISC 64-bit systems, 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 file 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().

dld_getenv()

Informs the dynamic loader that the environment variable SHLIB_PATH has been modified since program startup and the new value should be used for subsequent calls to shl_load().

MULTITHREAD USAGE

These routines are safe to be called from multithreaded applications.

Note: The 32-bit dynamic loader dld.sl serializes the loading and unloading of shared libraries in multithreaded applications using a pthread mutex lock. See the HP-UX Linker and Libraries Online User Guide for more information.

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

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 malloc(3C)).

On PA-RISC 32-bit systems, shl_unload() unloads the shared library regardless of whether there are other references to it. On PA-RISC 64-bit systems, a reference count is kept for each loaded library, and shl_unload() does not remove the shared library until all references are removed.

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(). On PA-RISC 64-bit systems, 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) should not be used as a dependency. If a dependent library contains TLS, and it is not loaded during program startup (that is, not linked against the executable), the dynamic loader fails to perform the operation.

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

AUTHOR

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

shl_load_pa(3X)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

Remarks

DESCRIPTION

MULTITHREAD USAGE

DIAGNOSTICS

ERRORS

WARNINGS

AUTHOR

SEE ALSO

System Tools

Miscellaneous

Texts and Tutorials