# dynlib

Dark Mode

- Manual
- Standard library
- Index
- devel, stable

Search:
Group by:

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 `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. 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