dynlib

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

Examples

Loading a simple C function

The following example demonstrates loading a function called 'greet' from a library that is determined at runtime based upon a language choice. If the library fails to load or the function 'greet' is not found, it quits with a failure error code.

import dynlib

type
  greetFunction = proc(): cstring {.gcsafe, stdcall.}

let lang = stdin.readLine()

let lib = case lang
of "french":
  loadLib("french.dll")
else:
  loadLib("english.dll")

if lib == nil:
  echo "Error loading library"
  quit(QuitFailure)

let greet = cast[greetFunction](lib.symAddr("greet"))

if greet == nil:
  echo "Error loading 'greet' function from library"
  quit(QuitFailure)

let greeting = greet()

echo greeting

unloadLib(lib)

Imports

strutils, posix

Types

LibHandle = pointer

a handle to a dynamically loaded library Source Edit

Procs

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

raises an EInvalidLibrary exception. Source Edit

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. Source Edit

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

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

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

loads a library with name matching pattern, similar to what dynlib 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. Source Edit

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

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

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

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

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

unloads the library lib Source Edit

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. Source Edit