Milo

Appearance

std/dl ​

Load shared libraries at run time (dlopen/dlsym). A plugin usually needs to call back into the host, so the host's own symbols must be visible: a function the library resolves against must be pub (or carry @externalLinkage), and on macOS the host must be linked with -Wl,-export_dynamic. On Linux the compiler already passes -rdynamic.

milo
from "std/dl" import { Lib, dlOpen, dlSelf }

API reference ​

Lib ​

milo
pub struct Lib

Owns the dlopen handle, so the pointer field makes it move-tracked: two copies would each close it. No @copy, on purpose. The field is private: a public one let any file point sym at an arbitrary address.

No Drop either, also on purpose: a library stays loaded until close. Pointers from sym are raw and routinely outlive the Lib binding (a callback table filled at startup), and unloading at the end of that binding's scope would leave each of them pointing at unmapped code.

Lib.close ​

milo
fn Lib.close(self: Lib): bool

Unload the library. Consumes the Lib: taking it by reference left a closed handle usable, so a second close or a sym after it reached the loader with a freed handle. Pointers obtained from sym() dangle afterwards, and any still-running thread the library started keeps running; closing does not stop it.

Lib.has ​

milo
fn Lib.has(self: &Lib, name: &string): bool

Whether a symbol is present, without treating absence as an error.

Lib.sym ​

milo
fn Lib.sym(self: &Lib, name: &string): Result<*u8, string>

Address of a symbol, for casting to an extern function-pointer type or reading as data. A symbol whose value is legitimately zero is indistinguishable from an error here, as with plain dlsym.

Functions ​

dlLastError ​

milo
pub fn dlLastError(): string

The most recent loader error, or a generic message when the loader has none. dlerror() also CLEARS the error, so this must be read exactly once per failure.

dlOpen ​

milo
pub fn dlOpen(path: &string): Result<Lib, string>

Load a shared library. path may be a filename resolved via the loader search path, or an explicit path.

dlSelf ​

milo
pub fn dlSelf(): Result<Lib, string>

A handle to the running program itself, for looking up symbols the executable exports. Requires the host's symbols to be exported, same as letting a loaded library resolve against the host — see the note at the top of this file.