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))
fis a function's name,formodule.f: not a function literal, a local holding a function, a method or a generic function.- Its parameters and its result are
int64,boolor, for the result,none: C calls it with machine words and nothing to count. - A C
intparameter arrives with its upper half undefined, as a Cintresult does; wrap it inc_intbefore 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
printftakes them, are onlyint64andbool: declare the function with...(see Extern functions) and pass numbers and addresses, but nodouble. - A C function that takes or returns a
structby value, or afloatordouble. Pointers to structs are fine:allocthe bytes C's layout needs andload/storethe fields at their offsets. - A function value, a closure, as a callback: only a named top-level function can be one (see Callbacks).