C ABI Reference

The complete specification of the C ABI surface that all language adapters call

The C ABI is the contract between the Rust core and every language adapter. It is defined by include/zinc.h, which is generated by the explicit header command and checked into the repository. Never edit this header by hand.

Types

typedef void *ZincHandle;

ZincHandle is an opaque pointer to an internal SharedRegion object. It is created by zinc_create or zinc_open, passed by value to all other functions, and freed by zinc_close. Pointer and capacity operations return null or zero for a null handle; notify and close do nothing. Wait operations return -22.

Function reference

zinc_create

int32_t zinc_create(const char *name,
                    uintptr_t capacity,
                    ZincHandle *out);

Creates a new shared memory region. The name must be a null-terminated C string matching [a-zA-Z0-9_-]+. The capacity must be a multiple of the system page size. On success, *out receives a new ZincHandle. The caller owns this handle and must eventually call zinc_close.

Returns 0 on success, or a negative error code.

zinc_open

int32_t zinc_open(const char *name,
                  ZincHandle *out);

Opens an existing shared region by name. On success, *out receives a new ZincHandle. The caller owns this handle.

Returns 0 on success, or a negative error code on failure (typically -2 for not found).

zinc_ptr

uint8_t *zinc_ptr(ZincHandle h);

Returns a raw pointer to the usable data area of the region (the next page after the header). The pointer is valid as long as the handle is not closed. Returns null if the handle is null.

The returned pointer points directly into the mmap’d memory. Processes share the same bytes, but applications must synchronize reads and writes.

zinc_capacity

uintptr_t zinc_capacity(ZincHandle h);

Returns the usable size of the region in bytes (total mapping size minus the first header page). Returns 0 if the handle is null.

zinc_close

void zinc_close(ZincHandle h);

Closes a handle obtained from zinc_create or zinc_open. Decrements the internal reference count. If the closing handle is the creator, the name is unlinked. Existing mappings remain valid until their handles close. Safe to call with a null handle (no-op).

After calling zinc_close, the handle is invalid and must not be passed to any other function.

zinc_notify

void zinc_notify(ZincHandle h);

Atomically increments the notification sequence counter and wakes all threads waiting on this region via zinc_wait. On Linux, this calls FUTEX_WAKE. On other platforms, it increments the counter. Safe to call with a null handle (no-op).

zinc_wait

int32_t zinc_wait(ZincHandle h,
                  uint32_t timeout_ms);

Blocks the calling thread until the notification sequence counter changes, or until timeout_ms milliseconds elapse. Uses a per-handle last_seq value to determine the expected counter value.

Returns 0 if the counter changed (data is available), -110 (ETIMEDOUT) if the timeout expired before any notification, or another negative error code. Returns -22 (EINVAL) if the handle is null.

zinc_version

uint32_t zinc_version(void);

Returns the library version encoded as (major << 16) | minor. Currently returns 0x00020001 (header version 2, ABI minor 1). Adapters should call this at initialization to verify binary compatibility with the loaded library.

Error return convention

All functions that can fail return int32_t. Zero means success. Negative values are POSIX error codes negated:

Constant	Value	Meaning
EEXIST	-17	Region name already exists
ENOENT	-2	Region name not found
EINVAL	-22	Invalid name, size, or handle
EAGAIN	-11	Ring buffer is full, or no notification is pending
ETIMEDOUT	-110	Wait timed out
EBADMSG	-74	Corrupted region (magic/version mismatch)
EPERM	-1	Permission denied

Platform I/O errors are returned as the negated OS error code.

Thread safety

All functions are thread-safe. The internal SharedRegion operations use atomic operations for reference counting and notification. The handle itself is not synchronized. Passing the same handle to two threads concurrently is safe as long as neither calls zinc_close while the other uses it.

zinc_try_wait

int32_t zinc_try_wait(ZincHandle h);

Consumes a pending notification without blocking. Returns 0 when the notification counter changed, -11 (EAGAIN, WouldBlock) when no change is pending, or -22 for a null handle. It shares the handle’s cursor with zinc_wait.

Pointer contracts

zinc_create and zinc_open reject null names and output pointers with -22. When an output pointer is valid, failure sets *out to null. Names must be readable, NUL-terminated UTF-8 strings; output pointers must point to writable handle storage.

Non-null handles must come from a successful create or open. Close each handle exactly once, after all waits and data access finish. A null handle is accepted by pointer, capacity, notify, and close operations. Invalid non-null pointers and handles used after close violate the C contract.