tango.sys.SharedLib

The shared library module provides a basic layer around the native functions used to load symbols from shared libraries.

License:

BSD style: see license.txt

Authors:

Tomasz Stachowiak, Anders Bergh
class SharedLib [final] #
SharedLib is an interface to system-specific shared libraries, such as ".dll", ".so" or ".dylib" files. It provides a simple interface to obtain symbol addresses (such as function pointers) from these libraries.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

void main() {
    if (auto lib = SharedLib.load(`c:\windows\system32\opengl32.dll`)) {
        Trace.formatln("Library successfully loaded");

        void* ptr = lib.getSymbol("glClear");
        if (ptr) {
            Trace.formatln("Symbol glClear found. Address = 0x{:x}", ptr);
        } else {
            Trace.formatln("Symbol glClear not found");
        }

        lib.unload();
    } else {
        Trace.formatln("Could not load the library");
    }

    assert (0 == SharedLib.numLoadedLibs);
}

This implementation uses reference counting, thus a library is not loaded again if it has been loaded before and not unloaded by the user. Unloading a SharedLib decreases its reference count. When it reaches 0, the shared library associated with it is unloaded and the SharedLib instance is deleted. Please do not delete SharedLib instances manually, unload() will take care of it.

Note:

SharedLib is thread-safe.
enum LoadMode #
Mapped from RTLD_NOW, RTLD_LAZY, RTLD_GLOBAL and RTLD_LOCAL
SharedLib load(char[] path, LoadMode mode = LoadMode.Now | LoadMode.Global) [static] #
Loads an OS-specific shared library.

Note:

Please use this function instead of the constructor, which is private.

Params:

pathThe path to a shared library to be loaded
modeLibrary loading mode. See LoadMode

Returns:

A SharedLib instance being a handle to the library, or throws SharedLibException if it could not be loaded
SharedLib loadNoThrow(char[] path, LoadMode mode = LoadMode.Now | LoadMode.Global) [static] #
Loads an OS-specific shared library.

Note:

Please use this function instead of the constructor, which is private.

Params:

pathThe path to a shared library to be loaded
modeLibrary loading mode. See LoadMode

Returns:

A SharedLib instance being a handle to the library, or null if it could not be loaded
void unload() #
Unloads the OS-specific shared library associated with this SharedLib instance.

Note:

It's invalid to use the object after unload() has been called, as unload() will delete it if it's not referenced any more.

Throws SharedLibException on failure. In this case, the SharedLib object is not deleted.

void unloadNoThrow() #
Unloads the OS-specific shared library associated with this SharedLib instance.

Note:

It's invalid to use the object after unload() has been called, as unload() will delete it if it's not referenced any more.
char[] path() #
Returns the path to the OS-specific shared library associated with this object.
void* getSymbol(char* name) #
Obtains the address of a symbol within the shared library

Params:

nameThe name of the symbol; must be a null-terminated C string

Returns:

A pointer to the symbol or throws SharedLibException if it's not present in the library.
void* getSymbolNoThrow(char* name) #
Obtains the address of a symbol within the shared library

Params:

nameThe name of the symbol; must be a null-terminated C string

Returns:

A pointer to the symbol or null if it's not present in the library.
uint numLoadedLibs() [static] #
Returns the total number of libraries currently loaded by SharedLib