Interoperability with C

All the supported C types have corresponding representations in Kotlin:

• Signed, unsigned integral, and floating point types are mapped to their Kotlin counterpart with the same width.

• Pointers and arrays are mapped to CPointer<T>?.

• Enums can be mapped to either Kotlin enum or integral values, depending on heuristics and the definition file settings.

• Structs and unions are mapped to types having fields available via the dot notation, i.e. someStructInstance.field1.

• typedef are represented as typealias.

Also, any C type has the Kotlin type representing the lvalue of this type, i.e., the value located in memory rather than a simple immutable self-contained value. Think C++ references as a similar concept. For structs (and typedefs to structs), this representation is the main one and has the same name as the struct itself. For Kotlin enums, it's named ${type}.Var; for CPointer<T>, it's CPointerVar<T>; and for most other types, it's ${type}Var.

For types that have both representations, the one with the lvalue has a mutable .value property for accessing the value.

val path = getenv("PATH")?.toKString() ?: ""

import kotlinx.cinterop.*

@OptIn(ExperimentalForeignApi::class)
fun shift(ptr: CPointer<ByteVar>, length: Int) {
    for (index in 0 .. length - 2) {
        ptr[index] = ptr[index + 1]
    }
}

import kotlinx.cinterop.*

@OptIn(ExperimentalForeignApi::class)
val intPtr = bytePtr.reinterpret<IntVar>()

import kotlinx.cinterop.*

@OptIn(ExperimentalForeignApi::class)
val intPtr: CPointer<IntVar> = bytePtr.reinterpret()

val longValue = ptr.toLong()
val originalPtr = longValue.toCPointer<T>()

The native memory can be allocated using the NativePlacement interface, for example:

import kotlinx.cinterop.*

@OptIn(ExperimentalForeignApi::class)
val byteVar = placement.alloc<ByteVar>()

Or:

import kotlinx.cinterop.*

@OptIn(ExperimentalForeignApi::class)
val bytePtr = placement.allocArray<ByteVar>(5)

The most logical placement is in the object nativeHeap. It corresponds to allocating native memory with malloc and provides an additional .free() operation to free allocated memory:

import kotlinx.cinterop.*

@OptIn(kotlinx.cinterop.ExperimentalForeignApi::class)
fun main() {
    val size: Long = 0
    val buffer = nativeHeap.allocArray<ByteVar>(size)
    nativeHeap.free(buffer)
}

nativeHeap requires memory to be freed manually. However, it's often useful to allocate memory with a lifetime bound to the lexical scope. It's helpful if such memory is freed automatically.

To address this, you can use memScoped { }. Inside the braces, the temporary placement is available as an implicit receiver, so it's possible to allocate native memory with alloc and allocArray, and the allocated memory will be automatically freed after leaving the scope.

For example, a C function returning values through pointer parameters can be used like:

import kotlinx.cinterop.*
import platform.posix.*

@OptIn(ExperimentalForeignApi::class)
val fileSize = memScoped {
    val statBuf = alloc<stat>()
    val error = stat("/", statBuf.ptr)
    statBuf.st_size
}

Although C pointers are mapped to the CPointer<T> type, C function pointer-typed parameters are mapped to CValuesRef<T>. When passing a CPointer<T> as a value of such a parameter, it's passed to the C function as is. However, a sequence of values can be passed instead of a pointer. In this case, the sequence is passed "by value", i.e., the C function receives the pointer to the temporary copy of that sequence, which is valid only until the function returns.

The CValuesRef<T> representation of pointer parameters is designed to support C array literals without explicit native memory allocation. To construct the immutable self-contained sequence of C values, the following methods are provided:

• ${type}Array.toCValues(), where type is the Kotlin primitive type

• Array<CPointer<T>?>.toCValues(), List<CPointer<T>?>.toCValues()

• cValuesOf(vararg elements: ${type}), where type is a primitive or pointer

For example:

// C:
void foo(int* elements, int count);
...
int elements[] = {1, 2, 3};
foo(elements, 3);

// Kotlin:

foo(cValuesOf(1, 2, 3), 3)

Unlike other pointers, the parameters of type const char* are represented as a Kotlin String. So it's possible to pass any Kotlin string to a binding expecting a C string.

There are also some tools available to convert between Kotlin and C strings manually:

• fun CPointer<ByteVar>.toKString(): String

• val String.cstr: CValuesRef<ByteVar>.

To get the pointer, .cstr should be allocated in native memory, for example:

val cString = kotlinString.cstr.getPointer(nativeHeap)

In all cases, the C string is supposed to be encoded as UTF-8.

To skip automatic conversion and ensure raw pointers are used in the bindings, add the noStringConversion property to the .def file:

noStringConversion = LoadCursorA LoadCursorW

This way, any value of type CPointer<ByteVar> can be passed as an argument of const char* type. If a Kotlin string should be passed, code like this could be used:

import kotlinx.cinterop.*

@OptIn(kotlinx.cinterop.ExperimentalForeignApi::class)
memScoped {
    LoadCursorA(null, "cursor.bmp".cstr.ptr)  // for ASCII or UTF-8 version
    LoadCursorW(null, "cursor.bmp".wcstr.ptr) // for UTF-16 version
}

It's possible to create a scope-stable pointer of C representation for the CValues<T> instance using the CValues<T>.ptr extension property, available under memScoped {}. It allows using APIs that require C pointers with a lifetime bound to a certain MemScope. For example:

import kotlinx.cinterop.*

@OptIn(kotlinx.cinterop.ExperimentalForeignApi::class)
memScoped {
    items = arrayOfNulls<CPointer<ITEM>?>(6)
    arrayOf("one", "two").forEachIndexed { index, value -> items[index] = value.cstr.ptr }
    menu = new_menu("Menu".cstr.ptr, items.toCValues().ptr)
    // ...
}

In this example, all values passed to the C API new_menu() have a lifetime of the innermost memScope it belongs to. Once the control flow leaves the memScoped scope, C pointers become invalid.

When a C function takes or returns a struct/union T by value, the corresponding argument type or return type is represented as CValue<T>.

CValue<T> is an opaque type, so the structure fields cannot be accessed with the appropriate Kotlin properties. This can be fine if an API uses structures as opaque handles. However, if field access is required, the following conversion methods are available:

• fun T.readValue(): CValue<T> converts (the lvalue) T to a CValue<T>. So to construct the CValue<T>, T can be allocated, filled, and then converted to CValue<T>.

• CValue<T>.useContents(block: T.() -> R): R temporarily stores the CValue<T> in memory, and then runs the passed lambda with this placed value T as receiver. So to read a single field, you can use the following code:

  val fieldValue = structValue.useContents { field }

• fun cValue(initialize: T.() -> Unit): CValue<T> applies the provided initialize function to allocate T in memory and converts the result into a CValue<T>.

• fun CValue<T>.copy(modify: T.() -> Unit): CValue<T> creates a modified copy of an existing CValue<T>. The original value is placed in memory, altered using the modify() function, and then converted back into a new CValue<T>.

• fun CValues<T>.placeTo(scope: AutofreeScope): CPointer<T> places the CValues<T> into an AutofreeScope, returning a pointer to the allocated memory. The allocated memory is automatically freed when the AutofreeScope is disposed.

To convert a Kotlin function to a pointer to a C function, you can use staticCFunction(::kotlinFunction). It's also possible to provide a lambda instead of a function reference. The function or lambda must not capture any values.

import kotlinx.cinterop.*

@OptIn(ExperimentalForeignApi::class)
val stableRef = StableRef.create(kotlinReference)
val voidPtr = stableRef.asCPointer()

@OptIn(ExperimentalForeignApi::class)
val stableRef = voidPtr.asStableRef<KotlinClass>()
val kotlinReference = stableRef.get()

stableRef.dispose()

Every C macro that expands to a constant is represented as a Kotlin property.

Macros without parameters are supported in cases when the compiler can infer the type:

int foo(int);
#define FOO foo(42)

In this case, FOO is available in Kotlin.

To support other macros, you can expose them manually by wrapping them with supported declarations. For example, function-like macro FOO can be exposed as a function foo() by adding custom declaration to the library:

headers = library/base.h

---

static inline int foo(int arg) {
    return FOO(arg);
}

Sometimes the C libraries have function parameters or struct fields of a platform-dependent type, for example, long or size_t. Kotlin itself doesn't provide either implicit integer casts or C-style integer casts (for example, (size_t) intValue), so to make writing portable code in such cases easier, the convert method is provided:

fun ${type1}.convert<${type2}>(): ${type2}

Here, each of type1 and type2 must be an integral type, either signed or unsigned.

.convert<${type}> has the same semantics as one of the .toByte, .toShort, .toInt, .toLong, .toUByte, .toUShort, .toUInt or .toULong methods, depending on type.

An example of using convert:

import kotlinx.cinterop.*
import platform.posix.*

@OptIn(ExperimentalForeignApi::class)
fun zeroMemory(buffer: COpaquePointer, size: Int) {
    memset(buffer, 0, size.convert<size_t>())
}

Also, the type parameter can be inferred automatically and so may be omitted in some cases.

Kotlin objects could be pinned, i.e. their position in memory is guaranteed to be stable until they are unpinned, and pointers to such objects' inner data could be passed to C functions.

There's a couple of approaches you can take:

• Use the usePinned service function that pins an object, executes a block, and unpins it on normal and exception paths:

  import kotlinx.cinterop.*
  import platform.posix.*
  
  @OptIn(ExperimentalForeignApi::class)
  fun readData(fd: Int) {
      val buffer = ByteArray(1024)
      buffer.usePinned { pinned ->
          while (true) {
              val length = recv(fd, pinned.addressOf(0), buffer.size.convert(), 0).toInt()
              if (length <= 0) {
                  break
              }
              // Now `buffer` has raw data obtained from the `recv()` call.
          }
      }
  }

  Here, pinned is an object of a special type Pinned<T>. It provides useful extensions like addressOf, which allows getting the address of a pinned array body.

• Use the refTo() function that has similar functionality under the hood but, in certain cases, may help you reduce boilerplate code:

  import kotlinx.cinterop.*
  import platform.posix.*
  
  @OptIn(ExperimentalForeignApi::class)
  fun readData(fd: Int) {
      val buffer = ByteArray(1024)
      while (true) {
          val length = recv(fd, buffer.refTo(0), buffer.size.convert(), 0).toInt()
  
          if (length <= 0) {
              break
          }
          // Now `buffer` has raw data obtained from the `recv()` call.
      }
  }

  Here, buffer.refTo(0) has the CValuesRef type that pins the array before entering the recv() function, passes the address of its zeroth element to the function, and unpins the array after exiting.

To import forward declarations, use the cnames package. For example, to import a cstructName forward declaration declared in a C library with a library.package, use a special forward declaration package: import cnames.structs.cstructName.

Consider two cinterop libraries: one that has a forward declaration of a struct and another with an actual implementation in another package:

// First C library
#include <stdio.h>

struct ForwardDeclaredStruct;

void consumeStruct(struct ForwardDeclaredStruct* s) {
    printf("Struct consumed\n");
}

// Second C library
// Header:
#include <stdlib.h>

struct ForwardDeclaredStruct {
    int data;
};

// Implementation:
struct ForwardDeclaredStruct* produceStruct() {
    struct ForwardDeclaredStruct* s = malloc(sizeof(struct ForwardDeclaredStruct));
    s->data = 42;
    return s;
}

To transfer objects between the two libraries, use an explicit as cast in your Kotlin code:

// Kotlin code:
fun test() {
    consumeStruct(produceStruct() as CPointer<cnames.structs.ForwardDeclaredStruct>)
}