# std/dynlib

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

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.

Example:

    import std/dynlib
    type
      GreetFunction = proc (): cstring {.gcsafe, stdcall.}

    proc loadGreet(lang: string) =
      let lib =
        case lang
        of "french":
          loadLib("french.dll")
        else:
          loadLib("english.dll")
      assert lib != nil, "Error loading library"

      let greet = cast[GreetFunction](lib.symAddr("greet"))
      assert greet != nil, "Error loading 'greet' function from library"

      echo greet()

      unloadLib(lib)

# Imports

strutils, posix

# Types

    LibHandle = pointer

  A handle to a dynamically loaded library. Source Edit

# Procs

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

  Retrieves the address of a procedure/variable from `lib`. Raises `LibraryError` if the symbol could not be found. Source Edit

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

  Given a library name pattern `s`, write possible library names to `dest`. Source Edit

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

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

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

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

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

  Loads a library with name matching `pattern`, similar to what the `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 raiseInvalidLibrary(name: cstring) {.noinline, noreturn,
        ...raises: [LibraryError], tags: [], forbids: [].}

  Raises a `LibraryError` exception. Source Edit

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

  Retrieves the address of a procedure/variable from `lib`. Returns nil if the symbol could not be found. Source Edit

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

  Unloads the library `lib`. Source Edit