pure/dynlib

  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 pure/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)

Types

LibHandle = pointer
A handle to a dynamically loaded library.   Source   Edit

Procs

proc checkedSymAddr(lib: LibHandle; name: cstring): pointer {.
    ...raises: [LibraryError], tags: [].}
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: [].}
Given a library name pattern s, write possible library names to dest.   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 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 loadLibPattern(pattern: string; globalSymbols = false): LibHandle {.
    ...raises: [], tags: [].}
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: [].}
Raises a LibraryError exception.   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
proc unloadLib(lib: LibHandle) {....gcsafe, raises: [], tags: [].}
Unloads the library lib.   Source   Edit