dynlib

A handle to a dynamically loaded library.

The file extension for dynamic libraries on the target OS.

Scans a dynamic library for symbols matching a struct's members, assigning found procedure pointers to the corresponding entry. Optionally takes a symbol prefix added to the struct's member name to construct the symbol looked up in the library. Optionally also takes the struct member to assign the library handle to, __handle by default.

This allows using one struct to hold library handles and symbol pointers for more than 1 dynamic library.

Loading the same library twice unloads the previous incarnation, allowing for straightforward hot reload support.

Returns: -1, false if the library could not be loaded. The number of symbols assigned on success. ok = true if count > 0

See doc.odin for an example.

Returns an error message for the last failed procedure call.

Loads a dynamic library from the filesystem. The paramater global_symbols makes the symbols in the loaded library available to resolve references in subsequently loaded libraries.

The parameter global_symbols is only used for the platforms linux, darwin, freebsd and openbsd. On windows this paramater is ignored.

The underlying behaviour is platform specific. On linux, darwin, freebsd and openbsd refer to dlopen. On windows refer to LoadLibraryW. Also temporarily needs an allocator to convert a string.

Example:

import "core:dynlib"
import "core:fmt"

load_my_library :: proc() {
	LIBRARY_PATH :: "my_library.dll"
	library, ok := dynlib.load_library(LIBRARY_PATH)
	if ! ok {
		fmt.eprintln(dynlib.last_error())
		return
	}
	fmt.println("The library %q was successfully loaded", LIBRARY_PATH)
}

Loads the address of a procedure/variable from a dynamic library.

The underlying behaviour is platform specific. On linux, darwin, freebsd and openbsd refer to dlsym. On windows refer to GetProcAddress. Also temporarily needs an allocator to convert a string.

Example:

import "core:dynlib"
import "core:fmt"

find_a_in_my_library :: proc() {
	LIBRARY_PATH :: "my_library.dll"
	library, ok := dynlib.load_library(LIBRARY_PATH)
	if ! ok {
		fmt.eprintln(dynlib.last_error())
		return
	}

	a, found_a := dynlib.symbol_address(library, "a")
	if found_a {
		fmt.printf("The symbol %q was found at the address %v", "a", a)
	} else {
		fmt.eprintln(dynlib.last_error())
	}
}

Unloads a dynamic library.

The underlying behaviour is platform specific. On linux, darwin, freebsd and openbsd refer to dlclose. On windows refer to FreeLibrary.

Example:

import "core:dynlib"
import "core:fmt"

load_then_unload_my_library :: proc() {
	LIBRARY_PATH :: "my_library.dll"
	library, ok := dynlib.load_library(LIBRARY_PATH)
	if ! ok {
		fmt.eprintln(dynlib.last_error())
		return
	}
	did_unload := dynlib.unload_library(library)
	if ! did_unload {
		fmt.eprintln(dynlib.last_error())
		return
	}
	fmt.println("The library %q was successfully unloaded", LIBRARY_PATH)
}