std/ffi

Types

CString

pub type CString = resource {
    // private fields omitted
}

Owned NUL-terminated copy of a String for passing to C; freed on drop.

CString.new

pub fn CString.new(text: &String) -> CString!

Copies text into a NUL-terminated buffer; fails when text contains an embedded NUL byte, since a C string can't represent one.

CString.ptr

pub fn CString.ptr(self) -> *const u8

Pointer to the buffer; valid while the CString lives.

CString.drop

pub fn CString.drop(move self)

Frees the buffer.

CValue

pub type CValue[T] = resource {
    // private fields omitted
}

C memory holding one value of T, freed on drop. T must be concrete (a layout(C) record, fixed-width number, Bool, Char or pointer), not a type parameter.

CValue.new

pub fn CValue.new[T](value: T) -> CValue[T]

Allocates C memory for value and copies it in.

CValue.ptr

pub fn CValue[T].ptr(self) -> *mut T

Pointer to the C memory; valid while the CValue lives.

CValue.get

pub fn CValue[T].get(self) -> T

A copy of the value as C currently holds it.

CValue.set

pub fn CValue[T].set(self, value: &T)

Overwrites the C memory with value.

CValue.drop

pub fn CValue[T].drop(move self)

Frees the C memory.

Pin

pub type Pin[T] = resource {
    // private fields omitted
}

A Kigumi value pinned for C as userdata; the pointer stays valid until drop.

Pin.new

pub fn Pin.new[T](value: T) -> Pin[T]

Pins value and takes ownership of it.

Pin.ptr

pub fn Pin[T].ptr(self) -> *mut u8

The userdata pointer to hand to C; valid while the Pin lives.

Pin.with

pub unsafe fn Pin.with[T, R](p: *mut u8, f: fn(&T) -> R) -> R

Runs f once on the value behind a userdata pointer that came from a live Pin[T]; f is not kept.

Pin.drop

pub fn Pin[T].drop(move self)

Releases the value.

Pin.release

pub fn Pin[T].release(move self) -> *mut u8

Gives up ownership without dropping: self is consumed, the pinned value stays alive, and the returned pointer can be handed to C to come back later through reclaim.

Pin.reclaim

pub unsafe fn Pin.reclaim[T](p: *mut u8) -> Pin[T]

Takes ownership back of a pointer previously returned by release; dropping the result drops the value. Reclaiming a pointer that was never released, or reclaiming one twice, is undefined.

RawHandle

pub type RawHandle layout(C) = {
    pub table i64
    pub slot i64
}

Carries a handle across a trusted in-process C boundary as plain integers; rebuild it on the way back with HandleTable.reclaim.

HandleFault

pub type HandleFault = Stale | WrongTable | OutOfRange

Why HandleTable.reclaim refused a RawHandle.

HandleTableBusy

pub type HandleTableBusy = {
    pub outstanding usize
}

Why HandleTable.close refused to close.

HandleTable

pub type HandleTable[T] = resource {
    // private fields omitted
}

A table of foreign-boundary handles for T; each slot's generation rejects a stale or replayed RawHandle, and a slot releases exactly once.

HandleTable.new

pub fn HandleTable.new[T]() -> HandleTable[T]

Creates an empty table.

HandleTable.insert

pub fn HandleTable[T].insert(self, value: T) -> FfiHandle[T]

Moves value into a fresh slot and returns an owned handle to it.

HandleTable.with

pub fn HandleTable[T].with[R](self, h: &FfiHandle[T], f: fn(&T) -> R) -> R

Runs f once with a borrow of h's value that cannot outlive the call and does not keep f; a direct getter would let the borrow escape.

HandleTable.remove

pub fn HandleTable[T].remove(self, h: FfiHandle[T]) -> T

Removes h from the table and returns its value; h's slot generation advances, so a RawHandle taken from h before this call becomes stale.

HandleTable.reclaim

pub unsafe fn HandleTable[T].reclaim(self, raw: RawHandle) -> Result[FfiHandle[T], HandleFault]

Reconstructs an owned handle from a RawHandle a foreign caller handed back; fails when it does not address a live slot of this exact table.

HandleTable.close

pub fn HandleTable[T].close(self) -> Result[Void, HandleTableBusy]

Reports whether the table can drop without aborting, without consuming self, so a caller on Err can clear handles and check again.

HandleTable.drop

pub fn HandleTable[T].drop(move self)

Drops the table; aborts if a handle is still outstanding, since drop cannot report an error — call close first to recover.

FfiHandle

pub type FfiHandle[T] = resource {
    // private fields omitted
}

An owned slot in a HandleTable.

FfiHandle.raw

pub fn FfiHandle[T].raw(self) -> RawHandle

The value to hand to foreign code; reconstruct it with HandleTable.reclaim.

FfiHandle.drop

pub fn FfiHandle[T].drop(move self)

Releases the slot and drops the value, like HandleTable.remove without using the result.

CError

pub type CError = {
    pub code i32
    pub text String
}

Error from a C call: the errno value and its text.

CError.message

pub fn CError.message(self) -> String

The error text.

Functions

errno

pub fn errno() -> i32

The C errno of the calling thread.

clearErrno

pub fn clearErrno()

Sets errno to 0; call before a C function that reports failure by clearing errno and leaving it clear, e.g. readdir(3) at end of stream.

null

pub pure fn null[T]() -> *const T

The null pointer.

isNull

pub pure fn isNull[T](p: *const T) -> Bool

Whether p is null.

toConst

pub pure fn toConst[T](p: *mut T) -> *const T

Drops mutability from a pointer.

toMut

pub unsafe fn toMut[T](p: *const T) -> *mut T

Adds mutability to a pointer; writing through it is the caller's responsibility.

offset

pub unsafe fn offset[T](p: *const T, bytes: Int) -> *const T

p moved by bytes.

string

pub unsafe fn string(p: *const u8) -> String

Copies the NUL-terminated text at p into a String; null gives "".

stringChecked

pub unsafe fn stringChecked(p: *const u8) -> String?

Like string, but None instead of a String that fails the UTF-8 invariant; null still gives Some("").

stringLossy

pub unsafe fn stringLossy(p: *const u8) -> String

Like string, but invalid UTF-8 becomes U+FFFD (replacement character) byte by byte instead of failing, for OS-controlled text that must stay usable regardless of encoding. The result cannot be converted back to the original bytes, so a name round-tripped this way may not refer to the same file on reopen.

readU8

pub unsafe fn readU8(p: *const u8) -> u8

Reads the value at p.

readI32

pub unsafe fn readI32(p: *const i32) -> i32

Reads the value at p.

readI64

pub unsafe fn readI64(p: *const i64) -> i64

Reads the value at p.

readF64

pub unsafe fn readF64(p: *const f64) -> f64

Reads the value at p.

writeU8

pub unsafe fn writeU8(p: *mut u8, value: u8)

Stores value at p.

writeI32

pub unsafe fn writeI32(p: *mut i32, value: i32)

Stores value at p.

writeI64

pub unsafe fn writeI64(p: *mut i64, value: i64)

Stores value at p.

writeF64

pub unsafe fn writeF64(p: *mut f64, value: f64)

Stores value at p.

sizeOf

pub pure fn sizeOf[T](value: &T) -> usize

Bytes a value of a layout(C) record occupies in C.

alignOf

pub pure fn alignOf[T](value: &T) -> usize

Bytes a value of a layout(C) record must be aligned to in C (layout(C, align: N) raises it to N when N is the larger of the two).

readRecord

pub unsafe fn readRecord[T](p: *const T) -> T

Copies the layout(C) record at p into a value.

writeRecord

pub unsafe fn writeRecord[T](p: *mut T, value: &T)

Stores a layout(C) record at p.

withAddress

pub fn withAddress[T, R](value: &mut T, f: fn(*mut T) -> R) -> R

Runs f with a raw pointer to value, valid only for the call: it cannot escape past f's own return. Use Pin for a pointer that must outlive it.

withAddressConst

pub fn withAddressConst[T, R](value: &T, f: fn(*const T) -> R) -> R

Like withAddress, but the pointer is read-only.

cast

pub pure fn cast[T](p: *const u8) -> *const T

Reinterprets a byte pointer as a pointer to T; reading through it is the caller's responsibility.

bytesFrom

pub unsafe fn bytesFrom(p: *const u8, n: usize) -> Bytes

Copies n bytes at p into a Bytes value.

bytesPtr

pub unsafe fn bytesPtr(b: &Bytes) -> *const u8

Pointer to the bytes; valid while b lives and is not changed.

secureEraseRaw

pub unsafe fn secureEraseRaw(p: *mut u8, n: usize)

Zeros n bytes at p like mem.secureErase; p..p+n must be valid and writable. Native-only.

readPtr

pub unsafe fn readPtr(p: *const u8) -> *const u8

Reads the pointer stored at p.

writePtr

pub unsafe fn writePtr(p: *mut u8, value: *const u8)

Stores value at p.

lastError

pub fn lastError() -> CError

The last C error of the calling thread as an error value.

errorText

pub fn errorText(code: i32) -> String

Text of a C errno value.