Error Codes

Every error code returned by the Zinc ABI and what it means

Zinc functions return 0 on success and negative POSIX error codes on failure. Language adapters translate these into native error types: Rust returns Result<T, ZincError>, Python raises OSError, Go returns error, and other languages throw exceptions.

Error enum

The Rust core defines a ZincError enum with these variants:

Variant	Error code	Trigger
AlreadyExists(String)	-17 (EEXIST)	create called with a name that is already in use
NotFound(String)	-2 (ENOENT)	open called with a name that has no active region
InvalidSize { page_size }	-22 (EINVAL)	create called with size 0 or not page-aligned
InvalidRingCapacity	-22 (EINVAL)	Capacity is not a power of two greater than one
OutOfBounds { offset, length, capacity }	-22 (EINVAL)	Rust data access exceeds the usable region
InvalidName	-22 (EINVAL)	Name is empty, too long, or contains invalid characters
PermissionDenied	-1 (EPERM)	OS permission check failed
Platform(io::Error)	OS-dependent	Other system or clock error
Syscall { syscall, source }	OS-dependent	Named OS call failed (shm_open, mmap, etc.)
WouldBlock	-11 (EAGAIN)	Non-blocking wait has no pending notification
RingFull	-11 (EAGAIN)	Ring cannot reserve the next slot
TimedOut	-110 (ETIMEDOUT)	wait returned without a notification
CorruptedRegion	-74 (EBADMSG)	Invalid mapping, header, capacity, or reference count on open

Error by scenario

When you encounter an error during development, this table can help identify the cause:

What you did	Likely error	Common cause
create("my-data", 16384) in two processes	AlreadyExists	Second process should use open, not create
open("my-data") before anyone calls create	NotFound	Check process startup order
create("", 16384)	InvalidName	Name must be non-empty
create("my data", 16384)	InvalidName	Name contains a space
create("test", 0)	InvalidSize	Capacity must be > 0 and page-aligned
create("test", 100)	InvalidSize	100 is not page-aligned
wait() times out	TimedOut	No one called notify, or timeout is too short
open() on a malformed region	CorruptedRegion	Mapping or header validation failed
open("my-data") after creator crashed	May succeed on stale storage	Crash recovery is not implemented

Error handling examples

Rust

let region = match SharedRegion::create("test", 16384) {
    Ok(region) => region,
    Err(ZincError::AlreadyExists(name)) => SharedRegion::open(&name)?,
    Err(error) => return Err(error),
};

Platform errors

Any system call can produce an OS-level error. Mapping calls use ZincError::Syscall { syscall, source }. The error code returned to the caller is the negated OS error code. Common platform errors:

Code	Meaning
EPERM (-1)	Zinc maps shm_open permission denial to this code
ENFILE (-23)	System-wide file descriptor limit
ENOMEM (-12)	Out of memory for mmap
EMFILE (-24)	Process file descriptor limit

Check return values during development. In production, handle at least AlreadyExists (fall back to open), NotFound (retry or log), and TimedOut (treat as a heartbeat miss).

Syscall { syscall, source } preserves the syscall name and operating-system error in Rust. The C ABI returns the negative errno. Permission failures from shm_open use PermissionDenied (-1).