plibraryloader.h File Reference

Shared library loader. More...

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

Go to the source code of this file.

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

Functions
P_LIB_API PLibraryLoader *	p_library_loader_new (const pchar *path)
	Loads a shared library.
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.
P_LIB_API void	p_library_loader_free (PLibraryLoader *loader)
	Frees memory and allocated resources of PLibraryLoader.
P_LIB_API pchar *	p_library_loader_get_last_error (PLibraryLoader *loader)
	Gets the last occurred error.
P_LIB_API pboolean	p_library_loader_is_ref_counted (void)
	Checks whether library loading subsystem uses reference counting.

Detailed Description

Shared library loader.

Author

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:

• 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.
• BeOS supports dynamic loading for add-ons only. It is also possible to load the same library several times independently (not like a traditional shared library).

Definition in file plibraryloader.h.

Typedef Documentation

PFuncAddr

typedef void(* PFuncAddr) (void)

Pointer to a function address.

Definition at line 83 of file plibraryloader.h.

PLibraryLoader

typedef struct PLibraryLoader_ PLibraryLoader

Opaque data structure to handle a shared library.

Definition at line 80 of file plibraryloader.h.

Function Documentation

p_library_loader_free()

P_LIB_API void p_library_loader_free

(

PLibraryLoader *

loader

)

Frees memory and allocated resources of PLibraryLoader.

Parameters

loader

PLibraryLoader object to free.

Since

0.0.1

p_library_loader_get_last_error()

P_LIB_API pchar * p_library_loader_get_last_error

(

PLibraryLoader *

loader

)

Gets the last occurred error.

Parameters

loader

PLibraryLoader object to get error for.

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.

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.

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

P_LIB_API pboolean p_library_loader_is_ref_counted

(

void

)

Checks whether library loading subsystem uses reference counting.

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.

p_library_loader_new()

P_LIB_API PLibraryLoader * p_library_loader_new

(

const pchar *

path

)

Loads a shared library.

Parameters

path	Path to the shared library file.

Returns

Pointer to PLibraryLoader in case of success, NULL otherwise.

Since

0.0.1

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.