Shared library loader. More...
Go to the source code of this file.
Typedefs | |
| 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... | |
Functions | |
| P_LIB_API PLibraryLoader * | p_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 pchar * | p_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.
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).
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.
- 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
loaderparameter 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()
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.
