Cross-platform loading of shared libraries/DLLs and their symbols. The behaviour of dynamically loaded libraries is specific to the target platform of the program. For in depth detail on the underlying behaviour please refer to your target platform's documentation. For a full example, see: [[ core/dynlib/example; https://github.com/odin-lang/Odin/tree/master/core/dynlib/example ]]

Collection Info

View Source
Collection
core
Path
dynlib
Entries
7
Constants 1
Jump to Constants
LIBRARY_FILE_EXTENSION
Types 1
Jump to Types
Library
Procedures 5
Jump to Procedures
initialize_symbols last_error load_library symbol_address unload_library
Procedure Groups 0
Variables 0

Source Files

(hidden platform specific files)

Constants

1

LIBRARY_FILE_EXTENSION #

Source 
LIBRARY_FILE_EXTENSION :: _LIBRARY_FILE_EXTENSION

The file extension for dynamic libraries on the target OS.

Types

1

Procedures

5

initialize_symbols #

Source 
initialize_symbols :: proc(symbol_table: ^$T, library_path: string, symbol_prefix: string = "", handle_field_name: string = "__handle") -> (count: int = -1, ok: bool = false) {…}

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.

last_error #

Source 
last_error :: proc() -> string {…}

Returns an error message for the last failed procedure call.

load_library #

Source 
load_library :: proc(path: string, global_symbols: bool = false, allocator := context.temp_allocator) -> (library: Library, did_load: bool) {…}

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) }

symbol_address #

Source 
symbol_address :: proc(library: Library, symbol: string, allocator := context.temp_allocator) -> (ptr: rawptr, found: bool) #optional_ok {…}

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()) } }

unload_library #

Source 
unload_library :: proc(library: Library) -> (did_unload: bool) {…}

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) }