zig-cinterop

Zig C Interop

Purpose

Guide agents through Zig's C interoperability: @cImport/@cInclude for calling C, translate-c for header inspection, extern struct and packed struct for ABI-compatible types, exporting Zig for C consumption, and zig cc for mixed C/Zig builds.

Triggers

• "How do I call a C function from Zig?"
• "How do I use @cImport and @cInclude?"
• "How do I export Zig functions to be called from C?"
• "How do I define a struct that matches a C struct?"
• "What does translate-c do?"
• "How do I build a mixed C and Zig project?"

Workflow

1. Calling C from Zig with @cImport

const c = @cImport({
    @cInclude("stdio.h");
    @cInclude("string.h");
    @cInclude("mylib.h");
    @cDefine("MY_FEATURE", "1");  // Equivalent to -DMY_FEATURE=1
    @cUndef("SOME_MACRO");
});

pub fn main() void {
    _ = c.printf("Hello from C: %d\n", @as(c_int, 42));

    var buf: [256]u8 = undefined;
    _ = c.snprintf(&buf, buf.len, "formatted: %d", @as(c_int, 100));
}

In build.zig:

exe.linkLibC();  // Required when using C functions
exe.addIncludePath(b.path("include/"));

2. translate-c — inspect C header translation

translate-c converts C headers to Zig declarations, letting you see exactly how Zig sees a C API:

# Translate a header file
zig translate-c /usr/include/stdio.h > stdio.zig

# Translate with defines/includes
zig translate-c -I include/ -DFEATURE=1 mylib.h > mylib.zig

# Translate and inspect specific types
zig translate-c mylib.h | grep -A5 "struct MyStruct"

This is Zig's equivalent of bindgen — you use it to understand what Zig generates, then use @cImport directly in code.

3. C type mapping

C type	Zig type
int	c_int
unsigned int	c_uint
long	c_long
unsigned long	c_ulong
long long	c_longlong
size_t	usize
ssize_t	isize
char *	[*:0]u8 (null-terminated)
const char *	[*:0]const u8
void *	*anyopaque
NULL	null
bool	bool (C99) or c_int (older)
float	f32
double	f64