Module dynlib

This module implements the ability to access symbols from shared libraries. On POSIX this uses the dlsym mechanism, on Windows LoadLibrary.

Imports

strutils

Types

LibHandle = pointer

a handle to a dynamically loaded library

Procs

proc raiseInvalidLibrary(name: cstring) {.noinline, noreturn, raises: [LibraryError],
                                       tags: [].}

raises an EInvalidLibrary exception.

proc checkedSymAddr(lib: LibHandle; name: cstring): pointer {.
    raises: [Exception, LibraryError], tags: [RootEffect].}

retrieves the address of a procedure/variable from lib. Raises EInvalidLibrary if the symbol could not be found.

proc libCandidates(s: string; dest: var seq[string]) {.raises: [], tags: [].}

given a library name pattern s write possible library names to dest.

proc loadLibPattern(pattern: string; global_symbols = false): LibHandle {.
    raises: [Exception], tags: [RootEffect].}

loads a library with name matching pattern, similar to what dlimport pragma does. Returns nil if the library could not be loaded. Warning: this proc uses the GC and so cannot be used to load the GC.

proc loadLib(path: string; global_symbols = false): LibHandle {.gcsafe, raises: [],
    tags: [].}

loads a library from path. Returns nil if the library could not be loaded.

proc loadLib(): LibHandle {.gcsafe, raises: [], tags: [].}

gets the handle from the current executable. Returns nil if the library could not be loaded.

proc unloadLib(lib: LibHandle) {.gcsafe, raises: [], tags: [].}

unloads the library lib

proc symAddr(lib: LibHandle; name: cstring): pointer {.gcsafe, raises: [], tags: [].}

retrieves the address of a procedure/variable from lib. Returns nil if the symbol could not be found.