Typedefs | Functions
plibraryloader.h File Reference

Shared library loader. More...

#include <pmacros.h>
#include <ptypes.h>
Include dependency graph for plibraryloader.h:

Go to the source code of this file.


typedef typedefP_BEGIN_DECLS struct PLibraryLoader_ PLibraryLoader
 Opaque data structure to handle a shared library. More...
typedef void(* PFuncAddr) (void)
 Pointer to a function address. More...


P_LIB_API PLibraryLoaderp_library_loader_new (const pchar *path)
 Loads a shared library. More...
P_LIB_API PFuncAddr p_library_loader_get_symbol (PLibraryLoader *loader, const pchar *sym)
 Gets a pointer to a symbol in the loaded shared library. More...
P_LIB_API void p_library_loader_free (PLibraryLoader *loader)
 Frees memory and allocated resources of PLibraryLoader. More...
P_LIB_API pcharp_library_loader_get_last_error (PLibraryLoader *loader)
 Gets the last occurred error. More...
P_LIB_API pboolean p_library_loader_is_ref_counted (void)
 Checks whether library loading subsystem uses reference counting. More...

Detailed Description

Shared library loader.

Alexander Saprykin

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:

Typedef Documentation

◆ PFuncAddr

typedef void(* PFuncAddr) (void)

Pointer to a function address.

◆ PLibraryLoader

typedef typedefP_BEGIN_DECLS struct PLibraryLoader_ PLibraryLoader

Opaque data structure to handle a shared library.

Function Documentation

◆ p_library_loader_free()

P_LIB_API void p_library_loader_free ( PLibraryLoader loader)

Frees memory and allocated resources of PLibraryLoader.

loaderPLibraryLoader object to free.

◆ p_library_loader_get_last_error()

P_LIB_API pchar* p_library_loader_get_last_error ( PLibraryLoader loader)

Gets the last occurred error.

loaderPLibraryLoader object to get error for.
Human readable error string in case of success, NULL otherwise.
0.0.3 loader parameter was added.
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.

◆ p_library_loader_get_symbol()

P_LIB_API PFuncAddr p_library_loader_get_symbol ( PLibraryLoader loader,
const pchar sym 

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

loaderPointer to the loaded shared library handle.
symName of the symbol.
Pointer to the symbol in case of success, NULL otherwise.

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

P_LIB_API pboolean p_library_loader_is_ref_counted ( void  )

Checks whether library loading subsystem uses reference counting.

TRUE in case of success, FALSE otherwise.

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.

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

◆ p_library_loader_new()

P_LIB_API PLibraryLoader* p_library_loader_new ( const pchar path)

Loads a shared library.

pathPath to the shared library file.
Pointer to PLibraryLoader in case of success, NULL otherwise.

If you are loading the already loaded shared library, an operating system increments corresponding reference count and decrements it after freeing PLibraryLoader, thus the shared library would be unloaded from the address space only when the counter becomes zero.