Skip to content

mohitmishra786/low-level-dev-skills / skills/zig/zig-cinterop

zig-cinterop

Verified

Zig 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.

FileKindSize
SKILL.mdskill md7.7 KB
references/translate-c-guide.mdmarkdown4.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;
};
```
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall