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
nbytes, returningdst. Complexity: O(n).
- Precondition:
dst != 0 - Precondition:
src != 0
fn c_memset(ptr: Int, value: Int, n: Int) -> Int¶
Fill
nbytes withvalue, returningptr. Complexity: O(n).
- Precondition:
ptr != 0
fn c_memcmp(a: Int, b: Int, n: Int) -> Int¶
Compare
nbytes (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_symon 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)¶
msgfollowed 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
lenbytes atoffset; 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