`uns`

Unsafe opt-in operations - every function requires a guard token (created with unsgu) as its first argument, making all unsafe usage explicit and grep-able. Provides raw box allocation, read/write, and direct syscall invocation with 0–6 positional arguments or a variadic list, plus an optional result-wrapping variant.

Load with: use uns

What this module does

uns is ilusm's explicit unsafe escape hatch. Rather than allowing arbitrary unsafe code anywhere, every uns function requires a guard - a tagged object created by unsgu("tag") - as its first argument. This means every call site is self-documenting and easy to audit with a grep for the guard name.

The syscall surface delegates to sysc.inv, which maps syscall numbers to host-native operations. This is the lowest-level layer in the stdlib, used by mem for arena management.

Quick example

use uns

# Create a named guard (the tag identifies this unsafe block)
g = uns.guard("my_ffi_block")

# Raw box operations
box = uns.raw_new(g, 42)
prn(uns.raw_get(g, box))   # 42
uns.raw_set(g, box, 99)
prn(uns.raw_get(g, box))   # 99

# Direct syscall (no args)
uns.sys0(g, 4)  # syscall #4

# Direct syscall with 2 args
uns.sys2(g, 7, "hello", 100)

# Variadic
uns.sys(g, 9, ["a", "b", "c"])

# With result wrapping
result = uns.sysres(g, 5, [ptr1, ptr2])

Functions

Guard

unsgu(tag) / uns.guard(tag)

Creates a guard token {t:"unsguard", tag}. tag must be a non-empty string. Pass this as the first argument to every other uns function.

unsas(g) / uns.assert(g)

Verifies that g is a valid guard. Throws if not. Called internally by all other functions.

Raw box operations

unsrn(g, v) / uns.raw_new(g, v)

Allocates a new ptr box holding v. Requires a valid guard.

unsrg(g, p) / uns.raw_get(g, p)

Reads the value from box p. Requires a valid guard.

unsrs(g, p, v) / uns.raw_set(g, p, v)

Writes v into box p. Requires a valid guard.

Syscall invocation

unss0(g, nr) / uns.sys0(g, nr)

Invokes syscall nr with no arguments.

unss1(g, nr, a0) / uns.sys1(…)

Invokes syscall nr with 1 argument.

unss2 … unss6 / uns.sys2 … uns.sys6

Invokes syscall nr with 2–6 positional arguments.

unssi(g, nr, args) / uns.sys(g, nr, args)

Invokes syscall nr with a variadic argument list.

unssr(g, nr, args) / uns.sysres(g, nr, args)

Invokes syscall nr and wraps the result via sysc.res.

Notes

Requires ptr, sysc, and eru.
All functions throw if the guard argument is not a valid unsguard object.