Skip to content

C interop ​

Mini calls C directly: no wrapper layer, no generated glue, no runtime shim. The API is the one of Kotlin/Native's kotlinx.cinterop, so code written for it mostly works unchanged. The sample below is compiled and run by the documentation checks.

kotlin
@file:Suppress("WRONG_MODIFIER_TARGET")
@file:CInclude("time.h")

import kotlin.native.CName
import kotlinx.cinterop.*

@CName("strlen")
external fun strlen(s: CPointer<ByteVar>): Long

@CName("qsort")
external fun qsort(base: COpaquePointer?, n: Long, size: Long, cmp: CPointer<CFunction<(COpaquePointer?, COpaquePointer?) -> Int>>)

@CStruct("tm")
external class Tm : CStructVar {
    var tm_sec: Int
    var tm_min: Int
    var tm_hour: Int
    var tm_mday: Int
    var tm_mon: Int
    var tm_year: Int
    var tm_wday: Int
    var tm_yday: Int
    var tm_isdst: Int
    var tm_gmtoff: Long
    var tm_zone: CPointer<ByteVar>?
}

@CName("gmtime_r")
external fun gmtime_r(t: CPointer<LongVar>, out: CPointer<Tm>): CPointer<Tm>?

val ascending = staticCFunction { a: COpaquePointer?, b: COpaquePointer? ->
    a!!.reinterpret<IntVar>().pointed.value - b!!.reinterpret<IntVar>().pointed.value
}

fun main() {
    memScoped {
        println(strlen("héllo".cstr.ptr))

        val numbers = allocArray<IntVar>(5)
        val values = intArrayOf(42, 7, 19, 3, 88)
        for (i in 0 until 5) numbers[i] = values[i]
        qsort(numbers, 5L, 4L, ascending)
        for (i in 0 until 5) print("" + numbers[i] + " ")
        println()

        val seconds = alloc<LongVar>()
        seconds.value = 86400L * 365L
        val tm = alloc<Tm>()
        gmtime_r(seconds.ptr, tm.ptr)
        println("" + (tm.tm_year + 1900) + "-" + (tm.tm_mon + 1) + "-" + tm.tm_mday)
    }
}
text
6
3 7 19 42 88 
1971-1-1

Calling C functions ​

external fun with @CName("symbol") is a direct call of the C function. Without @CName in your own files the Kotlin name is the symbol.

KotlinC
Byte, Short, Int, Longint8_t, int16_t, int32_t, int64_t (size_t and ssize_t are Long)
Float, Doublefloat, double
Booleanbool
Charuint16_t
Unitvoid
CPointer<T>, CPointer<T>?, COpaquePointerT *, void * (null is NULL)
CPointer<CFunction<(Int) -> Int>>int (*)(int)

Unsigned types do not exist yet: use the signed type of the same width. String, classes and structs by value have no C representation and are rejected with a clear message. Structs are passed by pointer only.

C functions with ... are declared once per call shape with @CVariadic(fixed), the number of leading fixed parameters:

kotlin
@CVariadic(3) @CName("snprintf")
external fun snprintfInt(buf: CPointer<ByteVar>, n: Long, fmt: CPointer<ByteVar>, v: Int): Int

@file:CInclude("header.h") is a real #include in the generated C file (headers next to your sources are found), @file:CLink("m") adds -lm to the link line, and minic build ... --c-src helper.c compiles and links your own C file. The LLVM backend takes the declarations from the Kotlin signatures and needs no headers. Only exported symbols can be called, not macros or static inline functions.

Memory and pointers ​

Pointers, IntVar and the other variables, and structs are plain machine addresses: a CPointer is one void *, never an object, never reference counted. They cannot be stored in Any, List or other generic code (a clear error tells you).

  • variables: ByteVar ShortVar IntVar LongVar FloatVar DoubleVar BooleanVar CPointerVar<T>, read and written with .value; x.ptr is the address, p.pointed the variable at an address, p.reinterpret<T>() a cast
  • arrays and arithmetic: allocArray<IntVar>(n), p[i], p[i] = v, p + n, p - n, p - q
  • sizeOf<T>() and alignOf<T>()
  • memScoped { ... } frees everything allocated in it when it ends, nativeHeap.alloc<T>() / nativeHeap.free(x) is malloc and free; both zero the memory
  • "text".cstr.ptr (inside memScoped) and p.toKString() convert UTF-8 C strings

Structs ​

kotlin
@file:Suppress("WRONG_MODIFIER_TARGET")

@CStruct("timespec")
external class Timespec : CStructVar {
    var tv_sec: Long
    var tv_nsec: Long
}

The properties are the fields in declaration order; the compiler lays them out with the C rules (natural alignment, padding) and sizeOf<Timespec>() agrees with the C compiler. A val property of another struct type is embedded in place, @CArray(16) val name: CPointer<ByteVar> is an array in place, and @CStruct("name", size = 64, align = 8) overrides the computed size or alignment. Arrays of structs: recs[i].field reads the i-th element in place.

The K2 frontend does not accept external class; the @file:Suppress("WRONG_MODIFIER_TARGET") line is what lets it, and the Mini frontend ignores it.

Callbacks ​

staticCFunction { a: Int, b: Int -> a + b } is a C function pointer. The lambda cannot capture anything (a C pointer has no place for state): that is a compile error. Pass state through a void * argument the C library hands back. A reference to a top-level function works too: staticCFunction(::compare). An exception that escapes a callback ends the program, because it cannot travel through C frames.

A function pointer is called like a function: val f: CPointer<CFunction<(Int, Int) -> Int>> = ...; f(1, 2).

Ownership ​

Pointers are checked like other owned values in Strict files (memory model):

  • memScoped is a Scoped allocator like Arena. A pointer into it that leaves the block (return, a field or global, an escaping lambda) is M0105.
kotlin
@file:MemoryMode(Mode.Strict)

import kotlinx.cinterop.*
import mini.memory.*

fun dangling(): CPointer<IntVar> {
    val p = memScoped {
        val x = alloc<IntVar>()
        x.value = 1
        x.ptr          // the memory is freed when memScoped ends
    }
    return p
}

fun main() {
    println(dangling().pointed.value)
}
  • nativeHeap is a Deallocating allocator: a missing free is M0102, a second one M0103, a use afterwards M0101.
  • A pointer returned by a C function is externally managed: no obligation, nobody may free it. @Owned(free = "fn") on the external fun says the caller owns the result and must release it by calling the C function fn, with the same M0102/M0103/M0101 checks:
kotlin
@Owned(free = "free") @CName("malloc")
external fun cMalloc(n: Long): CPointer<ByteVar>?
@CName("free")
external fun cFree(p: CPointer<ByteVar>?)

Limits ​

  • 64-bit targets only (pointers are 8 bytes); the 32-bit LLVM prototype has no interop.
  • No unsigned integer types, no structs or unions by value, no bit fields, no C varargs through Kotlin vararg.
  • @CName on a non-external function (exporting Kotlin code to C) and a binding generator from headers are planned, not done.

Released under the Apache License 2.0.