Skip to content

stdlib.ffi

FFI Library (C Foreign Function Interface)

Generated from v0.60.1. 4 source files, 79 documented symbols.

c.xi

fn c_strlen(ptr: Int) -> Int

Length of a null-terminated string. Complexity: O(len).

  • Precondition: ptr != 0
fn c_strcmp(a: Int, b: Int) -> Int

Lexicographic string comparison (negative / zero / positive). Complexity: O(min(len)).

  • Precondition: a != 0
  • Precondition: b != 0
fn c_strcpy(dst: Int, src: Int) -> Int

Copy a string, returning dst. Complexity: O(len(src)).

  • Precondition: dst != 0
  • Precondition: src != 0
fn c_memcpy(dst: Int, src: Int, n: Int) -> Int

Copy n bytes, returning dst. Complexity: O(n).

  • Precondition: dst != 0
  • Precondition: src != 0
fn c_memset(ptr: Int, value: Int, n: Int) -> Int

Fill n bytes with value, returning ptr. Complexity: O(n).

  • Precondition: ptr != 0
fn c_memcmp(a: Int, b: Int, n: Int) -> Int

Compare n bytes (negative / zero / positive). Complexity: O(n).

  • Precondition: a != 0
  • Precondition: b != 0
fn c_atoi(ptr: Int) -> Int

Parse a decimal string to Int. Complexity: O(len).

  • Precondition: ptr != 0
fn c_atof(ptr: Int) -> Float64

Parse a string to Float64. Complexity: O(len).

  • Precondition: ptr != 0
fn c_abs(n: Int) -> Int

Absolute value. Complexity: O(1).

  • Precondition: true
fn c_rand() -> Int

Pseudo-random integer. Complexity: O(1).

  • Precondition: true
fn c_srand(seed: Int)

Seed the C random generator. Complexity: O(1).

  • Precondition: true
fn c_clock() -> Int

Processor time consumed. Complexity: O(1).

  • Precondition: true
fn c_qsort(base: Int, n: Int, size: Int, cmp: Int)

Sort an array using a comparator callback (address of a C function). Complexity: O(n log n) average.

  • Precondition: base != 0
fn c_bsearch(key: Int, base: Int, n: Int, size: Int, cmp: Int) -> Int

Binary search in a sorted array. Returns the element address, or 0 when not found. Complexity: O(log n).

  • Precondition: base != 0



dl.xi

fn dl_open(path: Str) -> Result[Int, Str]

Load a shared library and return a handle (Int address), or Err. Complexity: O(1).

  • Precondition: true
fn dl_sym(handle: Int, name: Str) -> Result[Int, Str]

Resolve a symbol address in a library, or Err. Complexity: O(1).

  • Precondition: true
fn dl_close(handle: Int) -> Result[Unit, Str]

Unload a library. Complexity: O(1).

  • Precondition: true
fn dl_error() -> Str

Description of the last dynamic-loading error (OS error code). Complexity: O(1).

  • Precondition: true
fn dl_self() -> Int

Handle of the current executable. Complexity: O(1).

  • Precondition: true
fn dl_open_global(path: Str) -> Result[Int, Str]

Load a library with global symbol visibility. Windows resolves symbols with global visibility by default, so this is identical to dl_open. Complexity: O(1).

fn dl_sym_address(handle: Int, name: Str) -> Result[Int, Str]

Resolve a symbol as a data address. Identical to dl_sym on Windows. Complexity: O(1).

fn dl_has_symbol(handle: Int, name: Str) -> Bool

Whether a symbol exists in a library. Complexity: O(1).

  • Precondition: true



errno.xi

fn errno_get() -> Int

Read the current errno value (and record it as the snapshot). Reads the CRT errno cell byte-wise (64-bit little-endian). Complexity: O(1).

  • Precondition: true
fn errno_set(code: Int)

Set the errno value (byte-wise 64-bit little-endian store). Complexity: O(1).

fn errno_strerror(code: Int) -> Str

Human-readable message for an error code. Complexity: O(1).

  • Precondition: true
fn errno_perror(msg: Str)

Print msg followed by the current errno message. Complexity: O(1).

fn errno_last() -> Int

Last recorded errno (snapshot). Complexity: O(1).

fn errno_is_error(code: Int) -> Bool

Whether a code represents an error (non-zero). Complexity: O(1).

fn errno_name(code: Int) -> Str

Symbolic name for an error code (for example "ENOENT"). Unknown codes map to "UNKNOWN". Complexity: O(1).




ffi.xi

fn alloc(size: Int) -> *UInt8

---- Raw allocation / free (primitive, no wrapper) ----------------------------------------------------

  • Precondition: size > 0
  • Postcondition: result != null

fn free(ptr: *UInt8)

Free a C-allocated pointer.

  • Precondition: ptr != null

fn memcpy(dest: *UInt8, src: *UInt8, size: Int)

C memcpy over raw pointers.

  • Precondition: dest != null
  • Precondition: src != null
  • Precondition: size > 0

type SafePtr

---- SafePtr -- owned pointer with bounds tracking ------------------------------------------------------

Field Type
ptr *UInt8
size Int
owned Bool

fn safe_ptr_alloc(size: Int) -> Result[SafePtr, Str]

Allocate a new SafePtr. Calls xiom.ffi.alloc internally.

  • Precondition: size > 0

fn safe_ptr_from_raw(ptr: *UInt8, size: Int) -> Result[SafePtr, Str]

Wrap an externally-provided pointer (from a C library return value). The caller is responsible for lifetime management (owned = false).

  • Precondition: ptr != null
  • Precondition: size > 0

fn safe_ptr_free(ptr: SafePtr)

Free an owned SafePtr. No-op for non-owned pointers.

fn safe_ptr_read_byte(ptr: &SafePtr, offset: Int) -> Result[Int, Str]

Read a single byte at offset. Bounds-checked.

  • Precondition: offset >= 0

fn safe_ptr_write_byte(ptr: &mut SafePtr, offset: Int, val: Int) -> Result[Unit, Str]

Write a single byte at offset. Bounds-checked.

  • Precondition: offset >= 0

fn safe_ptr_read_i32(ptr: &SafePtr, offset: Int) -> Result[Int, Str]

Read a 32-bit signed integer at offset (little-endian). Bounds-checked. Bytes are combined as: b0 | b1<<8 | b2<<16 | b3<<24 with sign extension.

  • Precondition: offset >= 0

fn safe_ptr_write_i32(ptr: &mut SafePtr, offset: Int, val: Int) -> Result[Unit, Str]

Write a 32-bit signed integer at offset (little-endian). Bounds-checked. Decomposed into 4 bytes: byte i = (val >> (8*i)) & 0xFF.

  • Precondition: offset >= 0

fn safe_ptr_read_f32(ptr: &SafePtr, offset: Int) -> Result[Float32, Str]

Read a 32-bit float at offset. Bounds-checked. Uses *const Float32 pointer-cast for bit-level reinterpretation.

  • Precondition: offset >= 0

fn safe_ptr_write_f32(ptr: &mut SafePtr, offset: Int, val: Float32) -> Result[Unit, Str]

Write a 32-bit float at offset. Bounds-checked.

  • Precondition: offset >= 0

fn safe_ptr_read_u32(ptr: &SafePtr, offset: Int) -> Result[Int, Str]

Read a 32-bit unsigned integer at offset (little-endian). Bounds-checked. Result is always non-negative (0..4294967295).

  • Precondition: offset >= 0

fn safe_ptr_write_u32(ptr: &mut SafePtr, offset: Int, val: Int) -> Result[Unit, Str]

Write a 32-bit unsigned integer at offset (little-endian). Bounds-checked. Writes the lower 32 bits of val.

  • Precondition: offset >= 0

fn safe_ptr_read_i64(ptr: &SafePtr, offset: Int) -> Result[Int, Str]

Read a 64-bit signed integer at offset (little-endian). Bounds-checked. Bytes combined: b0 | b1<<8 | ... | b7<<56 with sign extension.

  • Precondition: offset >= 0

fn safe_ptr_write_i64(ptr: &mut SafePtr, offset: Int, val: Int) -> Result[Unit, Str]

Write a 64-bit signed integer at offset (little-endian). Bounds-checked.

  • Precondition: offset >= 0

fn safe_ptr_read_f64(ptr: &SafePtr, offset: Int) -> Result[Float64, Str]

Read a 64-bit float at offset. Bounds-checked. Uses *const Float64 pointer-cast for bit-level reinterpretation.

  • Precondition: offset >= 0

fn safe_ptr_write_f64(ptr: &mut SafePtr, offset: Int, val: Float64) -> Result[Unit, Str]

Write a 64-bit float at offset. Bounds-checked.

  • Precondition: offset >= 0

fn safe_ptr_read_u16(ptr: &SafePtr, offset: Int) -> Result[Int, Str]

Read a 16-bit unsigned integer at offset (little-endian). Bounds-checked. Result is in range 0..65535.

  • Precondition: offset >= 0

fn safe_ptr_write_u16(ptr: &mut SafePtr, offset: Int, val: Int) -> Result[Unit, Str]

Write a 16-bit unsigned integer at offset (little-endian). Bounds-checked. Writes the lower 16 bits of val.

  • Precondition: offset >= 0

fn safe_ptr_fill(ptr: &mut SafePtr, value: Int) -> Result[Unit, Str]

Fill the entire SafePtr buffer with a byte value. Bounds-safe (uses size field). Complexity: O(n), where n = ptr.size.

  • Precondition: value >= 0
  • Precondition: value <= 255

fn safe_ptr_copy(dst: &mut SafePtr, src: &SafePtr, count: Int) -> Result[Unit, Str]

Copy count bytes from src to dst. Bounds-checked against both SafePtr sizes. Complexity: O(count).

  • Precondition: count >= 0

fn safe_ptr_to_vec(ptr: &SafePtr) -> Result[Vec[Int], Str]

Copy all bytes from a SafePtr into a Vec[Int]. Each byte becomes a separate Int element. Result length equals ptr.size.

fn ptr_read_u8(p: *UInt8) -> Int

Raw unsafe read of a UInt8 at pointer p. SAFETY: caller must ensure p points to valid memory. No bounds check.

  • Precondition: p != null

fn ptr_write_u8(p: *UInt8, v: Int)

Raw unsafe write of a UInt8 at pointer p. SAFETY: caller must ensure p points to valid mutable memory. No bounds check.

  • Precondition: v >= 0
  • Precondition: v <= 255

fn ptr_read_u32_le(p: *UInt8) -> Int

Raw unsafe read of a 32-bit unsigned integer at pointer p (little-endian). SAFETY: caller must ensure p and p+0..p+3 point to valid memory. No bounds check.

  • Precondition: p != null

fn ptr_write_u32_le(p: *UInt8, v: Int)

Raw unsafe write of a 32-bit unsigned integer at pointer p (little-endian). Writes the lower 32 bits of v. SAFETY: caller must ensure p+0..p+3 point to valid mutable memory. No bounds check.

  • Precondition: v >= 0

fn ptr_read_u64_le(p: *UInt8) -> Int

Raw unsafe read of a 64-bit unsigned integer at pointer p (little-endian). SAFETY: caller must ensure p+0..p+7 point to valid memory. No bounds check.

  • Precondition: p != null

fn ptr_write_u64_le(p: *UInt8, v: Int)

Raw unsafe write of a 64-bit unsigned integer at pointer p (little-endian). Writes the lower 64 bits of v. SAFETY: caller must ensure p+0..p+7 point to valid mutable memory. No bounds check.

  • Precondition: p != null

type FFIBuffer

---- FFIBuffer -- growable byte buffer with capacity guard --------------------------------------

Field Type
data Vec[Int]
capacity Int

fn buffer_new(capacity: Int) -> Result[FFIBuffer, Str]

Allocate an FFI byte buffer; Err on failure.

  • Precondition: capacity > 0

fn buffer_write(buf: &mut FFIBuffer, data: &Vec[Int]) -> Result[Int, Str]

Append Int byte values; Ok(bytes written) or Err.

  • Precondition: data.len() > 0

fn buffer_read(buf: &FFIBuffer, offset: Int, len: Int) -> Result[Vec[Int], Str]

Read len bytes at offset; Ok(values) or Err.

  • Precondition: offset >= 0
  • Precondition: len > 0

fn buffer_clear(buf: &mut FFIBuffer)

Reset the buffer length to zero.

fn buffer_len(buf: &FFIBuffer) -> Int

Current buffer length in bytes.

fn buffer_is_empty(buf: &FFIBuffer) -> Bool

True when the buffer is empty.

type FFIError

---- FFIError -- C error code translation ------------------------------------------------------------------------

Field Type
code Int
message Str

fn ffi_check(code: Int, msg: Str) -> Result[Int, FFIError]

C convention: negative return code = error.

fn ffi_check_ptr(ptr: *UInt8, msg: Str) -> Result[*UInt8, FFIError]

C convention: null pointer = error.

  • Precondition: true

fn ffi_check_nonzero(code: Int, msg: Str) -> Result[Int, FFIError]

C convention: non-zero return = error.

fn ffi_ok() -> Int

FFI success code (0).

fn ffi_error(code: Int, msg: Str) -> FFIError

FFI error value from a code and message.

fn write_u32_at(dest: Int, offset: Int, value: Int)

Write a UInt32 at a byte offset into a raw pointer (C struct field).

  • Precondition: dest != 0
  • Precondition: offset >= 0

fn write_u64_at(dest: Int, offset: Int, value: Int)

Write a UInt64 at a byte offset.

  • Precondition: dest != 0
  • Precondition: offset >= 0

fn write_f32_at(dest: Int, offset: Int, value: Float32)

Write a Float32 at a byte offset.

  • Precondition: dest != 0
  • Precondition: offset >= 0

fn write_str_at(dest: Int, offset: Int, s: Str)

Write a null-terminated string at a byte offset.

  • Precondition: dest != 0
  • Precondition: offset >= 0

fn size_of[T]() -> Int

---- Utility --------------------------------------------------------------------------------------------------------------------------------

fn align_of[T]() -> Int

Alignment of T in bytes (0 when unknown).

fn extern_c(name: Str) -> Int

FFI extern-C symbol handle by name.

  • Precondition: name.len() > 0