mohitmishra786/low-level-dev-skills / skills/zig/zig-cinterop
zig-cinterop
VerifiedZig C interoperability skill. Use when calling C from Zig, calling Zig from C, translating headers with b.addTranslateC or @cImport, running translate-c on C headers, defining extern structs and packed structs, matching C ABI types, or building mixed C/Zig projects. Activates on queries about addTranslateC, @cImport, @cInclude, translate-c, extern struct, packed struct, Zig C ABI, calling C from Zig, exporting Zig to C, or bindgen equivalents.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.7 KB |
| references/translate-c-guide.md | markdown | 4.7 KB |
references/translate-c-guide.md
View on GitHub# translate-c Guide and C ABI Types Reference
## Using translate-c
### Basic usage
```bash
# Translate a system header
zig translate-c /usr/include/fcntl.h 2>/dev/null | head -100
# Translate with include paths and defines
zig translate-c \
-I /usr/include \
-I ./vendor/mylib/include \
-DLINUX \
-D_GNU_SOURCE \
./vendor/mylib/include/mylib.h > mylib_translated.zig
# Cross-platform translation
zig translate-c \
-target aarch64-linux-gnu \
/usr/include/sys/socket.h > socket_arm.zig
```
### What translate-c produces
Given C:
```c
typedef struct {
int x;
int y;
float z;
} Vec3;
int process(Vec3 *v, size_t count, const char *name);
#define MAX_ITEMS 1024
```
translate-c generates:
```zig
pub const Vec3 = extern struct {
x: c_int = @import("std").mem.zeroes(c_int),
y: c_int = @import("std").mem.zeroes(c_int),
z: f32 = @import("std").mem.zeroes(f32),
};
pub extern fn process(v: ?*Vec3, count: usize, name: ?[*:0]const u8) c_int;
pub const MAX_ITEMS = @as(c_int, 1024);
```
### Workflow: translate-c → addTranslateC
1. Run `zig translate-c` to see Zig's interpretation of the C API
2. Identify type mappings, function signatures, pointer nullability
3. In real code, translate headers with `b.addTranslateC` in `build.zig` and `@import` the module
(`@cImport` does the same inline but is deprecated since 0.16)
4. Only use the translated output as a manual reference, not as source
## C ABI Type Mapping Reference
### Integer types
| C | Zig builtin | Notes |
|---|------------|-------|
| `char` | `u8` / `i8` | Sign is implementation-defined |
| `signed char` | `i8` | Always signed |
| `unsigned char` | `u8` | Always unsigned |
| `short` | `c_short` | Platform-dependent size |
| `unsigned short` | `c_ushort` | |
| `int` | `c_int` | Typically 32-bit |
| `unsigned int` | `c_uint` | |
| `long` | `c_long` | 32-bit on Windows, 64-bit on Linux/macOS |
| `unsigned long` | `c_ulong` | |
| `long long` | `c_longlong` | 64-bit |
| `unsigned long long` | `c_ulonglong` | |
| `size_t` | `usize` | |
| `ssize_t` | `isize` | |
| `ptrdiff_t` | `isize` | |
| `intptr_t` | `isize` | |
| `uintptr_t` | `usize` | |
| `int8_t` | `i8` | |
| `uint8_t` | `u8` | |
| `int16_t` | `i16` | |
| `uint16_t` | `u16` | |
| `int32_t` | `i32` | |
| `uint32_t` | `u32` | |
| `int64_t` | `i64` | |
| `uint64_t` | `u64` | |
### Pointer types
| C | Zig |
|---|-----|
| `void *` | `*anyopaque` |
| `const void *` | `*const anyopaque` |
| `char *` (null-terminated) | `[*:0]u8` |
| `const char *` (null-terminated) | `[*:0]const u8` |
| `char *` (known length) | `[*]u8` or `[]u8` |
| `T *` (nullable) | `?*T` |
| `T *` (non-null) | `*T` |
| `T **` | `*?*T` or `**T` |
| `void (*fn)(int)` | `?*const fn (c_int) callconv(.c) void` |
### Enum types
```c
// C enum
typedef enum {
STATUS_OK = 0,
STATUS_ERR = 1,
STATUS_BUSY = 2,
} Status;
```
```zig
// Zig equivalent with C ABI
const Status = enum(c_int) {
ok = 0,
err = 1,
busy = 2,
};
```
## Common Patterns
### Callback functions (function pointers)
```c
// C API with callback
typedef void (*callback_t)(void *ctx, int event);
void register_callback(callback_t cb, void *ctx);
```
```zig
const c = @import("c"); // b.addTranslateC module, see SKILL.md section 1
fn my_callback(ctx: ?*anyopaque, event: c_int) callconv(.c) void {
const self: *MyType = @ptrCast(@alignCast(ctx));
self.handle(event);
}
// Register
c.register_callback(my_callback, &my_obj);
```
### Error handling (C errno pattern)
```zig
// c.h: #include <fcntl.h> <unistd.h> <string.h>
const c = @import("c");
fn openFile(path: [*:0]const u8) !void {
const fd = c.open(path, c.O_RDONLY);
if (fd < 0) {
const err = std.c._errno().*; // portable; avoids glibc-only __errno_location
const msg = c.strerror(err);
std.log.err("open failed: {s}", .{msg});
return error.OpenFailed;
}
defer _ = c.close(fd);
}
```
### Memory management with C allocator
```zig
// c.h: #include <stdlib.h> <string.h>
const c = @import("c");
// Allocate C memory (must free with c.free)
const buf = c.malloc(1024) orelse return error.OutOfMemory;
defer c.free(buf);
const typed: [*]u8 = @ptrCast(buf);
// Use Zig allocator as C allocator via std.heap.c_allocator
const allocator = std.heap.c_allocator;
const data = try allocator.alloc(u8, 1024);
defer allocator.free(data);
```
## Null Safety
Zig's pointer model forces explicit null handling:
```zig
// C: char *result = get_name(id); // might return NULL
// Zig: ?[*:0]const u8
const result: ?[*:0]const u8 = c.get_name(id);
if (result) |name| {
std.debug.print("name: {s}\n", .{name});
} else {
std.debug.print("not found\n", .{});
}
// Or with orelse
const name = c.get_name(id) orelse {
return error.NotFound;
};
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |