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:

Authors:
Tomasz Stachowiak, Anders Bergh

class SharedLib;
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:
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: int;
Mapped from RTLD_NOW, RTLD_LAZY, RTLD_GLOBAL and RTLD_LOCAL

static SharedLib load(const(char)[] path, LoadMode mode = LoadMode.Now | LoadMode.Global);
Loads an OS-specific shared library.

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

Params:
const(char)[] path The path to a shared library to be loaded
LoadMode mode Library loading mode. See LoadMode

Returns:
A SharedLib instance being a handle to the library, or throws SharedLibException if it could not be loaded

static SharedLib loadNoThrow(const(char)[] path, LoadMode mode = LoadMode.Now | LoadMode.Global);
Loads an OS-specific shared library.

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

Params:
const(char)[] path The path to a shared library to be loaded
LoadMode mode Library 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.

@property const(char)[] path();
Returns the path to the OS-specific shared library associated with this object.

void* getSymbol(const(char)* name);
Obtains the address of a symbol within the shared library

Params:
const(char)* name The 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(const(char)* name);
Obtains the address of a symbol within the shared library

Params:
const(char)* name The 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.

static uint numLoadedLibs();
Returns the total number of libraries currently loaded by SharedLib


Page generated by Ddoc. Copyright (C) 2007 Tomasz Stachowiak