plibsys

#include <pmacros.h>
#include <ptypes.h>

Go to the source code of this file.

## Typedefs

Opaque data structure to handle a shared library. More...

Pointer to a function address. More...

## Functions

Gets a pointer to a symbol in the loaded shared library. More...

Frees memory and allocated resources of PLibraryLoader. More...

Gets the last occurred error. More...

## Detailed Description

All modern operating systems support dynamic loadable objects. Such objects are compiled with special flags and can be loaded by other programs and libraries later at the runtime. These loadable objects often called as the shared libraries, though some platforms even allow to treat the program binary as a loadable object, too.

When the program is linked with a shared library its dependency would be resolved by the operating system automatically before starting the program. But in some circumstances you may need to load a shared library object explicitly (i.e. implementing a plugin subsystem, checking for API availability).

All functions and variables which a shared library is exporting are called symbols. Usually only the exported symbols are available from outside the shared library. Actually all those symbols represent a library API.

Use p_library_loader_new() to load a shared library and p_library_loader_get_symbol() to retrieve a pointer to a symbol within it. Close the library after usage with p_library_loader_free().

Please note the following platform specific differences:

• HP-UX doesn't support loading libraries containing TLS and built with static TLS model. The same rule applies to any library used as dependency. HP-UX on 32-bit PA-RISC systems doesn't support reference counting for loaded libraries when using shl_* family of functions (always removes all library references on unload).
• On OpenVMS only shareable images (linked with /SHAREABLE) can be used for dynamic symbol resolving. Usually they have .EXE extension.

## Typedef Documentation

Opaque data structure to handle a shared library.

## Function Documentation

Frees memory and allocated resources of PLibraryLoader.

Parameters
Since
0.0.1

Gets the last occurred error.

Parameters
Returns
Human readable error string in case of success, NULL otherwise.
Since
0.0.1
Version
0.0.3 loader parameter was added.
Note
Caller takes ownership of the returned string.

The NULL result may indicate that no error was occurred since the last call.

Different operating systems have different behavior on error indicating. Some systems reset an error status before the call, some do not. Some systems write the successful call result (usually zero) to the error status, thus resetting an error from the previous call.

Some operating systems may return last error even if library handler was not created. In that case try to pass NULL value as a parameter.

Gets a pointer to a symbol in the loaded shared library.

Parameters
 loader Pointer to the loaded shared library handle. sym Name of the symbol.
Returns
Pointer to the symbol in case of success, NULL otherwise.
Since
0.0.1

Since the symbol may have a NULL value, the returned NULL value from this call actually doesn't mean the failed result. You can additionally check the error result using p_library_loader_get_last_error().

 P_LIB_API pboolean p_library_loader_is_ref_counted ( void )

Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.3

When reference counting is supported, the same shared library can be opened several times, but it would be completely unloaded from the memory only when the last reference to it is removed.

Note
For now, only HP-UX on 32-bit PA-RISC systems with shl_* model doesn't support reference counting.