FFI Helper APIs

In Rtinycc: Builds the 'TinyCC' Command-Line Interface and Library for 'C' Scripting in 'R'

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
tcc_cstring <- Rtinycc::tcc_cstring
tcc_data_ptr <- Rtinycc::tcc_data_ptr
tcc_free <- Rtinycc::tcc_free
tcc_malloc <- Rtinycc::tcc_malloc
tcc_null_ptr <- Rtinycc::tcc_null_ptr
tcc_ptr_addr <- Rtinycc::tcc_ptr_addr
tcc_ptr_is_null <- Rtinycc::tcc_ptr_is_null
tcc_ptr_is_owned <- Rtinycc::tcc_ptr_is_owned
tcc_ptr_set <- Rtinycc::tcc_ptr_set
tcc_read_bytes <- Rtinycc::tcc_read_bytes
tcc_read_cstring <- Rtinycc::tcc_read_cstring
tcc_read_f64 <- Rtinycc::tcc_read_f64
tcc_read_i32 <- Rtinycc::tcc_read_i32
tcc_write_bytes <- Rtinycc::tcc_write_bytes
tcc_write_f64 <- Rtinycc::tcc_write_f64
tcc_write_i32 <- Rtinycc::tcc_write_i32

The helper APIs are the low-level tools you use when a binding needs explicit memory management, pointer inspection, or typed reads and writes.

Allocation and Ownership

The owned-memory helpers are tcc_malloc() and tcc_cstring().

buf <- tcc_malloc(16)
str_ptr <- tcc_cstring("hello")

tcc_ptr_is_owned(buf)
tcc_ptr_is_owned(str_ptr)

Both return owned external pointers. They can be freed explicitly with tcc_free() and also carry finalizers.

tcc_free(buf)
tcc_free(str_ptr)

Reading and Writing Raw Bytes

buf <- tcc_malloc(8)
tcc_write_bytes(buf, as.raw(1:8))
tcc_read_bytes(buf, 8)
tcc_free(buf)

Typed Reads and Writes

The helper layer also exposes typed accessors for primitive values at byte offsets.

buf <- tcc_malloc(16)
tcc_write_i32(buf, 0L, 42L)
tcc_write_f64(buf, 8L, 3.5)

tcc_read_i32(buf, offset = 0L)
tcc_read_f64(buf, offset = 8L)

tcc_free(buf)

These helpers are useful for manual struct-like layouts, output buffers, or pointer-heavy APIs that do not map cleanly onto ordinary R vectors.

Pointer-to-Pointer Helpers

Some C APIs fill outputs through T ** or void **. Rtinycc exposes a small set of helpers for that pattern.

ptr_size <- if (!is.null(.Machine$sizeof.pointer)) .Machine$sizeof.pointer else 8L
ptr_ref <- tcc_malloc(ptr_size)
target <- tcc_malloc(4)

tcc_ptr_set(ptr_ref, target)
tcc_ptr_addr(tcc_data_ptr(ptr_ref))
tcc_ptr_addr(target)

tcc_ptr_set(ptr_ref, tcc_null_ptr())
tcc_ptr_is_null(tcc_data_ptr(ptr_ref))

tcc_free(target)
tcc_free(ptr_ref)

tcc_data_ptr() returns a borrowed pointer view. It is not an owned allocation.

C String Helpers

str_ptr <- tcc_cstring("Hello, world")
tcc_read_cstring(str_ptr)
tcc_read_cstring(str_ptr, max_bytes = 5)
tcc_free(str_ptr)

This helper is the safe way to allocate a C-owned NUL-terminated string when the callee expects a mutable or longer-lived char *.

Rtinycc documentation built on April 28, 2026, 1:07 a.m.