Skip to content

Calling C with unsafe

stdlib/unsafe.kod lets Kod code call C functions that take buffers, write results through pointers, or deal in C strings. It reads and writes raw memory, so nothing checks what it does: a wrong address or size corrupts the program or crashes it, without an error that says why. Code that uses it says so with import "unsafe", and the rest of the program doesn't need it.

import "unsafe"

extern func pipe(anon fds: int64) -> int64
extern func getenv(anon name: int64) -> int64

func make_pipe() -> [int64] {
    let fds = unsafe.alloc(8)               // room for two C ints
    if unsafe.c_int(pipe(fds)) < 0 {
        panic(f"pipe failed: errno {unsafe.errno()}")
    }
    let ends = [unsafe.load32(fds), unsafe.load32(fds + 4)]
    unsafe.free(fds)
    return ends
}

func home() -> str {
    let name = "HOME"
    let value = getenv(unsafe.c_str(name))  // a `char *`, or 0
    if value == 0 {
        return ""
    }
    return unsafe.str_at(value)             // a copy in a Kod `str`
}

The libc module

stdlib/libc.kod declares the C library functions the standard library calls (read, write, close, pipe, kill, waitpid, posix_spawnp and its file actions, getenv, setenv, and so on), with pointers as int64. Import it to call one as libc.read(fd, buf, n) instead of declaring it again; that also keeps the C name out of the module's own names, so a module can have a kill or poll of its own.

Addresses

An address is an int64, and arithmetic on it is ordinary arithmetic: fds + 4 is four bytes further on. Pass one to an extern parameter of type int64 where C takes a pointer, and take one back the same way. 0 is C's NULL.

Function Meaning
alloc(size) size bytes of zeroed memory, from C's heap; a program that runs out of memory panics
free(addr) give back what alloc returned; 0 does nothing
load8(addr) the byte at addr, 0 to 255
load32(addr) the 4 bytes at addr as a signed C int
load64(addr) the 8 bytes at addr
store8(addr, v), store32(addr, v), store64(addr, v) write the low 1, 4 or 8 bytes of v at addr
copy_out(addr, n) the n bytes at addr as a new bytes
copy_in(addr, data) write the bytes of data at addr

Memory from alloc isn't counted or freed for you: free it when C is done with it. Loads and stores are single instructions; 4- and 8-byte ones should be at an address that is a multiple of their size, as C would place them.

Strings and bytes

Function Meaning
c_str(s) the address of the bytes of the str s, followed by a 0 byte: a char * for C to read
data(b) the address of the bytes of the bytes b, for C to read
str_at(addr) a copy of the C string at addr, up to its 0 byte, as a str

c_str and data don't copy: the address is good only while s or b is, so keep the value in a variable for as long as C uses the address, and don't let C change the bytes. A str with a 0 byte inside looks shorter to C; check for one first where that matters. To give C a buffer it writes into, alloc one and copy_out what it wrote.

C's int and errno

Function Meaning
c_int(x) the low 4 bytes of x as a signed C int
errno() C's errno for this thread, as the last failed call left it

A C function that returns int leaves the upper half of the 8-byte result undefined, so wrap its result in c_int before comparing it: -1 may otherwise read as 4294967295. A function returning long, ssize_t, size_t or a pointer fills all 8 bytes. Read errno() straight after the call that failed: anything else in between, a print too, may change it.

Callbacks

c_function(f) is the address of the top-level function f, for a C function that calls back, such as qsort's comparison:

extern func qsort(anon base: int64, anon count: int64, anon size: int64, anon compare: int64) -> none

// C passes the addresses of two of the int64s being sorted.
func by_value(anon a: int64, anon b: int64) -> int64 {
    let x = unsafe.load64(a)
    let y = unsafe.load64(b)
    if x < y {
        return -1
    }
    if x > y {
        return 1
    }
    return 0
}

qsort(nums, count, 8, unsafe.c_function(by_value))
  • f is a function's name, f or module.f: not a function literal, a local holding a function, a method or a generic function.
  • Its parameters and its result are int64, bool or, for the result, none: C calls it with machine words and nothing to count.
  • A C int parameter arrives with its upper half undefined, as a C int result does; wrap it in c_int before using it.
  • C calls it on whatever thread C runs, and Kod's heap isn't safe to use from two threads at once, so a callback C makes from a thread of its own must not allocate. Inside a signal handler, likewise, it may only load and store.

What doesn't fit

  • Variable arguments, as printf takes them, are only int64 and bool: declare the function with ... (see Extern functions) and pass numbers and addresses, but no double.
  • A C function that takes or returns a struct by value, or a float or double. Pointers to structs are fine: alloc the bytes C's layout needs and load/store the fields at their offsets.
  • A function value, a closure, as a callback: only a named top-level function can be one (see Callbacks).