# Learn Zig Series (#28) - C Interop: Exposing Zig to C ![zig.png](https://images.hive.blog/DQmaHuB6qTWHaSpJHQ1S8FCCRmNQuUxTcPZdU4yKHsJ7vEP/zig-banner.png) ### What will I learn - You will learn the `export` keyword for making Zig functions callable from C; - You will learn the C calling convention (`callconv(.c)`) and why it matters; - You will learn building Zig as a static or shared library for C consumers; - You will learn struct layout compatibility between C and Zig using `extern struct`; - You will learn callback functions: passing Zig function pointers to C code; - You will learn ABI considerations: alignment, padding, and platform differences; - You will learn a practical example: writing a Zig library usable from Python via ctypes. ### Requirements - A working modern computer running macOS, Windows or Ubuntu; - An installed Zig 0.14+ distribution (download from ziglang.org); - The ambition to learn Zig programming. ### Difficulty - Intermediate ### Curriculum (of the `Learn Zig Series`): - [Zig Programming Tutorial - ep001 - Intro](https://hive.blog/programming/@scipio/zig-programming-tutoroial-ep001-intro) - [Learn Zig Series (#2) - Hello Zig, Variables and Types](https://hive.blog/hive-196387/@scipio/learn-zig-series-2-hello-zig-variables-and-types) - [Learn Zig Series (#3) - Functions and Control Flow](https://hive.blog/hive-196387/@scipio/learn-zig-series-3-functions-and-control-flow) - [Learn Zig Series (#4) - Error Handling (Zig's Best Feature)](https://hive.blog/hive-196387/@scipio/learn-zig-series-4-error-handling-zigs-best-feature) - [Learn Zig Series (#5) - Arrays, Slices, and Strings](https://hive.blog/hive-196387/@scipio/learn-zig-series-5-arrays-slices-and-strings) - [Learn Zig Series (#6) - Structs, Enums, and Tagged Unions](https://hive.blog/hive-196387/@scipio/learn-zig-series-6-structs-enums-and-tagged-unions) - [Learn Zig Series (#7) - Memory Management and Allocators](https://hive.blog/hive-196387/@scipio/learn-zig-series-7-memory-management-and-allocators) - [Learn Zig Series (#8) - Pointers and Memory Layout](https://hive.blog/hive-196387/@scipio/learn-zig-series-8-pointers-and-memory-layout) - [Learn Zig Series (#9) - Comptime (Zig's Superpower)](https://hive.blog/hive-196387/@scipio/learn-zig-series-9-comptime-zigs-superpower) - [Learn Zig Series (#10) - Project Structure, Modules, and File I/O](https://hive.blog/hive-196387/@scipio/learn-zig-series-10-project-structure-modules-and-file-io) - [Learn Zig Series (#11) - Mini Project: Building a Step Sequencer](https://hive.blog/hive-196387/@scipio/learn-zig-series-11-mini-project-building-a-step-sequencer) - [Learn Zig Series (#12) - Testing and Test-Driven Development](https://hive.blog/hive-196387/@scipio/learn-zig-series-12-testing-and-test-driven-development) - [Learn Zig Series (#13) - Interfaces via Type Erasure](https://hive.blog/hive-196387/@scipio/learn-zig-series-13-interfaces-via-type-erasure) - [Learn Zig Series (#14) - Generics with Comptime Parameters](https://hive.blog/hive-196387/@scipio/learn-zig-series-14-generics-with-comptime-parameters) - [Learn Zig Series (#15) - The Build System (build.zig)](https://hive.blog/hive-196387/@scipio/learn-zig-series-15-the-build-system-buildzig) - [Learn Zig Series (#16) - Sentinel-Terminated Types and C Strings](https://hive.blog/hive-196387/@scipio/learn-zig-series-16-sentinel-terminated-types-and-c-strings) - [Learn Zig Series (#17) - Packed Structs and Bit Manipulation](https://hive.blog/hive-196387/@scipio/learn-zig-series-17-packed-structs-and-bit-manipulation) - [Learn Zig Series (#18) - Async Concepts and Event Loops](https://hive.blog/hive-196387/@scipio/learn-zig-series-18-async-concepts-and-event-loops) - [Learn Zig Series (#18b) - Addendum: Async Returns in Zig 0.16](https://hive.blog/hive-196387/@scipio/learn-zig-series-18b-addendum-async-returns-in-zig-016) - [Learn Zig Series (#19) - SIMD with @Vector](https://hive.blog/hive-196387/@scipio/learn-zig-series-19-simd-with-vector) - [Learn Zig Series (#20) - Working with JSON](https://hive.blog/hive-196387/@scipio/learn-zig-series-20-working-with-json) - [Learn Zig Series (#21) - Networking and TCP Sockets](https://hive.blog/hive-196387/@scipio/learn-zig-series-21-networking-and-tcp-sockets) - [Learn Zig Series (#22) - Hash Maps and Data Structures](https://hive.blog/hive-196387/@scipio/learn-zig-series-22-hash-maps-and-data-structures) - [Learn Zig Series (#23) - Iterators and Lazy Evaluation](https://hive.blog/hive-196387/@scipio/learn-zig-series-23-iterators-and-lazy-evaluation) - [Learn Zig Series (#24) - Logging, Formatting, and Debug Output](https://hive.blog/hive-196387/@scipio/learn-zig-series-24-logging-formatting-and-debug-output) - [Learn Zig Series (#25) - Mini Project: HTTP Status Checker](https://hive.blog/hive-196387/@scipio/learn-zig-series-25-mini-project-http-status-checker) - [Learn Zig Series (#26) - Writing a Custom Allocator](https://hive.blog/hive-196387/@scipio/learn-zig-series-26-writing-a-custom-allocator) - [Learn Zig Series (#27) - C Interop: Calling C from Zig](https://hive.blog/hive-196387/@scipio/learn-zig-series-27-c-interop-calling-c-from-zig) - [Learn Zig Series (#28) - C Interop: Exposing Zig to C](https://hive.blog/hive-196387/@scipio/learn-zig-series-28-c-interop-exposing-zig-to-c) (this post) # Learn Zig Series (#28) - C Interop: Exposing Zig to C ## Solutions to Episode 27 Exercises **Exercise 1** - Zig-friendly wrapper around C's `localtime` and `strftime`: ```zig const std = @import("std"); const c = @cImport({ @cInclude("time.h"); @cInclude("stdio.h"); }); const DateTime = struct { raw: c.time_t, pub fn now() DateTime { var t: c.time_t = undefined; _ = c.time(&t); return .{ .raw = t }; } pub fn format(self: DateTime, buf: []u8, fmt: [:0]const u8) []const u8 { const tm = c.localtime(&self.raw); if (tm == null) return buf[0..0]; const written = c.strftime(buf.ptr, buf.len, fmt.ptr, tm); return buf[0..written]; } }; pub fn main() void { const dt = DateTime.now(); var buf1: [64]u8 = undefined; var buf2: [64]u8 = undefined; var buf3: [64]u8 = undefined; const iso = dt.format(&buf1, "%Y-%m-%d"); const full = dt.format(&buf2, "%d/%m/%Y %H:%M:%S"); const day_name = dt.format(&buf3, "%A %B %d"); std.debug.print("ISO: {s}\n", .{iso}); std.debug.print("Full: {s}\n", .{full}); std.debug.print("Day name: {s}\n", .{day_name}); } ``` The key insight: `localtime` returns a `?*c.struct_tm` -- a nullable pointer to a static internal buffer. We check for null before passing it to `strftime`. The wrapper hides all the C pointer mechanics behind a clean Zig interface: call `now()`, then `format()` with a buffer and a format string. **Exercise 2** - Wrapping C's `qsort` for `f64` slices: ```zig const std = @import("std"); const c = @cImport({ @cInclude("stdlib.h"); }); fn compareF64(a_ptr: ?*const anyopaque, b_ptr: ?*const anyopaque) callconv(.c) c_int { const a: *const f64 = @ptrCast(@alignCast(a_ptr)); const b: *const f64 = @ptrCast(@alignCast(b_ptr)); if (a.* < b.*) return -1; if (a.* > b.*) return 1; return 0; } fn sortF64(slice: []f64) void { c.qsort( @ptrCast(slice.ptr), slice.len, @sizeOf(f64), &compareF64, ); } pub fn main() void { var data = [_]f64{ 3.14, 1.0, 2.718, 0.5, 9.81, 1.414, 6.28 }; std.debug.print("Before qsort: ", .{}); for (data) |v| std.debug.print("{d:.3} ", .{v}); std.debug.print("\n", .{}); sortF64(&data); std.debug.print("After qsort: ", .{}); for (data) |v| std.debug.print("{d:.3} ", .{v}); std.debug.print("\n", .{}); // Verify against Zig's own sort var check = [_]f64{ 3.14, 1.0, 2.718, 0.5, 9.81, 1.414, 6.28 }; std.mem.sort(f64, &check, {}, std.sort.asc(f64)); var match = true; for (data, check) |a, b| { if (a != b) { match = false; break; } } std.debug.print("Matches Zig sort: {}\n", .{match}); } ``` The critical part is `callconv(.c)` on the comparison function. Without it, Zig uses its own calling convention, and `qsort` (which expects the C calling convention) would pass arguments in the wrong registers. The `?*const anyopaque` parameter types match C's `const void*`. We cast them to `*const f64` inside. **Exercise 3** - Mini key-value store with `qsort` and `bsearch`: ```zig const std = @import("std"); const c = @cImport({ @cInclude("stdlib.h"); @cInclude("string.h"); }); const Entry = extern struct { key: [32]u8, value: [64]u8, }; fn compareEntry(a_ptr: ?*const anyopaque, b_ptr: ?*const anyopaque) callconv(.c) c_int { const a: *const Entry = @ptrCast(@alignCast(a_ptr)); const b: *const Entry = @ptrCast(@alignCast(b_ptr)); return c.strcmp(&a.key, &b.key); } fn makeEntry(key: []const u8, value: []const u8) Entry { var e: Entry = .{ .key = [_]u8{0} ** 32, .value = [_]u8{0} ** 64 }; const klen = @min(key.len, 31); const vlen = @min(value.len, 63); @memcpy(e.key[0..klen], key[0..klen]); @memcpy(e.value[0..vlen], value[0..vlen]); return e; } fn lookup(store: []Entry, key: []const u8) ?[]const u8 { var search_key: Entry = .{ .key = [_]u8{0} ** 32, .value = [_]u8{0} ** 64 }; const klen = @min(key.len, 31); @memcpy(search_key.key[0..klen], key[0..klen]); const result = c.bsearch( @ptrCast(&search_key), @ptrCast(store.ptr), store.len, @sizeOf(Entry), &compareEntry, ); if (result) |found_ptr| { const entry: *const Entry = @ptrCast(@alignCast(found_ptr)); return std.mem.sliceTo(&entry.value, 0); } return null; } pub fn main() void { var store = [_]Entry{ makeEntry("apple", "A round fruit"), makeEntry("banana", "A yellow fruit"), makeEntry("cherry", "A small red fruit"), makeEntry("date", "A sweet desert fruit"), makeEntry("elderberry", "A dark purple berry"), makeEntry("fig", "A soft pear-shaped fruit"), makeEntry("grape", "Grows in clusters"), makeEntry("honeydew", "A type of melon"), makeEntry("kiwi", "Brown outside green inside"), makeEntry("lemon", "Very sour citrus"), }; // Sort by key first (bsearch requires sorted data) c.qsort(@ptrCast(&store), store.len, @sizeOf(Entry), &compareEntry); // Successful lookups for ([_][]const u8{ "apple", "fig", "lemon" }) |key| { if (lookup(&store, key)) |val| { std.debug.print("{s}: {s}\n", .{ key, val }); } } // Failed lookup if (lookup(&store, "mango")) |_| { std.debug.print("Should not reach\n", .{}); } else { std.debug.print("mango: not found\n", .{}); } } ``` The `extern struct` declaration is critical here. Regular Zig structs can reorder fields and add padding however the compiler likes. `extern struct` guarantees C-compatible layout -- fields in declaration order, with C-standard padding rules. Without `extern`, `bsearch` and `qsort` would read memory at wrong offsets and produce garbage. Here we go! Last time in [episode 27](https://hive.blog/hive-196387/@scipio/learn-zig-series-27-c-interop-calling-c-from-zig) we covered calling C code from Zig -- importing headers with `@cImport`, type mappings, linking libraries, wrapping C APIs into safe Zig interfaces. That's one direction of the interop story. Today we flip it around: making your Zig code callable FROM C. Why would you want this? Think about it. You've got a massive existing C codebase -- maybe a game engine, an embedded system firmware, a database, whatever -- and you want to write a new module in Zig. Better safety, better ergonomics, comptime, all the good stuff. But the rest of the system is C and it needs to call your new code. Or maybe you're writing a library in Zig that you want other languages to use. Python, Ruby, Lua, Node.js -- they all have C FFI interfaces. If your Zig library looks like a C library from the outside, every language with a C FFI can use it. That's a HUGE reach. Zig makes this remarkably straightforward. A few keywords, a couple of build system flags, and your Zig functions are callable from C (or anything that speaks the C ABI) with zero overhead ;-) ## The `export` keyword The `export` keyword is how you tell Zig "make this symbol visible in the compiled output with a stable, C-compatible name". Without it, Zig mangles function names, optimizes things away, and generally does whatever it wants with your symbols. With `export`, the function gets a predictable name that C linkers can find: ```zig // mathlib.zig export fn add(a: i32, b: i32) i32 { return a + b; } export fn multiply(a: i32, b: i32) i32 { return a * b; } export fn factorial(n: u32) u64 { if (n <= 1) return 1; var result: u64 = 1; var i: u32 = 2; while (i <= n) : (i += 1) { result *= @as(u64, i); } return result; } // This function is NOT exported -- internal only fn helperFunction() void { // C can't see this } ``` When you compile this into a library, the symbols `add`, `multiply`, and `factorial` appear in the symbol table with exactly those names. No mangling, no prefixes, no suffixes. A C program can link against the library and call `add(3, 4)` as if it was written in C. The `export` keyword also implies `callconv(.c)` -- the C calling convention. You don't need to specify it separately. This means the function uses the platform's standard calling convention (System V AMD64 ABI on Linux/macOS x86_64, Microsoft x64 on Windows, AAPCS on ARM, etc.). Arguments go in the right registers, return values come back in the right place, the stack gets cleaned up correctly. Everything the C side expects. ## The C calling convention and `callconv(.c)` Sometimes you need the C calling convention without exporting. This comes up when you're writing callback functions -- Zig functions that get called by C code through function pointers. We saw this briefly in the exercise solutions above with `qsort`. Let me show you the full picture: ```zig const std = @import("std"); // An exported function -- visible to C, uses C calling convention export fn processData(data: [*]const u8, len: usize) i32 { var sum: i32 = 0; for (data[0..len]) |byte| { sum += @as(i32, byte); } return sum; } // A callback function -- not exported, but uses C calling convention // so C code can call it through a function pointer fn onProgress(current: c_int, total: c_int, user_data: ?*anyopaque) callconv(.c) void { _ = user_data; std.debug.print("Progress: {d}/{d}\n", .{ current, total }); } // You can take the address of a callconv(.c) function // and pass it wherever C expects a function pointer export fn getProgressCallback() *const fn (c_int, c_int, ?*anyopaque) callconv(.c) void { return &onProgress; } ``` The difference between `export fn` and `fn ... callconv(.c)`: - `export fn` makes the symbol visible in the binary AND uses the C calling convention. Other code can link to it by name. - `fn ... callconv(.c)` uses the C calling convention but does NOT export the symbol. You pass it as a function pointer, not by name. If you call `export fn` from other Zig code in the same compilation unit, the compiler can still inline it and optimize normally. The export is for the linker's benefit, not a performance penalty. There's also `callconv(.naked)` for functions with no prologue/epilogue (useful for interrupt handlers or trampolines in OS dev), and `callconv(.inline)` which forces inlining. But for C interop, `.c` is what you need practically always. ## Building Zig as a static or shared library Alright, knowing the keywords is one thing. Actually building a usable library is another. Here's a complete `build.zig` that produces both a static library (`.a` on Linux/macOS, `.lib` on Windows) and a shared library (`.so`, `.dylib`, `.dll`): ```zig // build.zig const std = @import("std"); pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); // Static library const static_lib = b.addStaticLibrary(.{ .name = "zigmath", .root_source_file = b.path("src/mathlib.zig"), .target = target, .optimize = optimize, }); b.installArtifact(static_lib); // Shared library const shared_lib = b.addSharedLibrary(.{ .name = "zigmath", .root_source_file = b.path("src/mathlib.zig"), .target = target, .optimize = optimize, }); b.installArtifact(shared_lib); // Also install the auto-generated C header static_lib.installHeader(b.path("src/mathlib.zig"), "zigmath.h"); } ``` After `zig build`, you'll find: - `zig-out/lib/libzigmath.a` -- the static library - `zig-out/lib/libzigmath.so` (or `.dylib` on macOS) -- the shared library The static library gets linked directly into the final executable -- the linker copies the object code. The shared library gets loaded at runtime -- smaller executables, but you need to distribute the `.so` alongside your program. Which one should you use? Static is simpler (one binary, no DLL hell, no `LD_LIBRARY_PATH` nonsense). Shared is better when multiple programs use the same library (shared memory, smaller total disk usage) or when you want to update the library without recompiling every consumer. For the C side, you'd use the library like this: ```c // main.c #include // Declare the Zig functions extern int add(int a, int b); extern int multiply(int a, int b); extern unsigned long long factorial(unsigned int n); int main() { printf("add(3, 4) = %d\n", add(3, 4)); printf("multiply(6, 7) = %d\n", multiply(6, 7)); printf("factorial(10) = %llu\n", factorial(10)); return 0; } ``` Compile and link: `gcc main.c -L./zig-out/lib -lzigmath -o demo`. That's it. The C compiler doesn't know or care that those functions were written in Zig. They look exactly like C functions from the linker's perspective. ## Struct layout compatibility: `extern struct` This is a topic I've seen trip up a lot of people. Regular Zig structs and C structs have **different layout rules**. Zig's compiler is free to reorder fields, insert arbitrary padding, or pack things however it wants for performance. C structs follow strict rules: fields appear in declaration order, padding follows the platform's alignment requirements. If you're passing structs across the C boundary, you MUST use `extern struct`: ```zig const std = @import("std"); // Regular Zig struct -- field order and padding are compiler's choice const ZigPoint = struct { x: f64, y: f64, label: u8, }; // C-compatible struct -- fields in declaration order, C padding rules const CPoint = extern struct { x: f64, y: f64, label: u8, }; // Export functions that use C-compatible structs export fn createPoint(x: f64, y: f64, label: u8) CPoint { return .{ .x = x, .y = y, .label = label }; } export fn distanceBetween(a: *const CPoint, b: *const CPoint) f64 { const dx = a.x - b.x; const dy = a.y - b.y; return @sqrt(dx * dx + dy * dy); } pub fn main() void { std.debug.print("ZigPoint size: {d}, align: {d}\n", .{ @sizeOf(ZigPoint), @alignOf(ZigPoint), }); std.debug.print("CPoint size: {d}, align: {d}\n", .{ @sizeOf(CPoint), @alignOf(CPoint), }); const a = createPoint(0.0, 0.0, 'A'); const b = createPoint(3.0, 4.0, 'B'); const dist = distanceBetween(&a, &b); std.debug.print("Distance: {d:.2}\n", .{dist}); } ``` On a typical 64-bit system, `CPoint` will be 24 bytes: 8 for `x`, 8 for `y`, 1 for `label`, then 7 bytes of padding to align the struct to 8 bytes (since the largest field is `f64` which requires 8-byte alignment). This matches exactly what a C compiler would produce for the equivalent `struct CPoint { double x; double y; unsigned char label; };`. If you used a regular Zig `struct` instead, the compiler might (and often does) rearrange fields or use different padding. The C side would read `x` where `label` is, and you'd get garbage. This is not a theoretical concern -- it will absolutely happen in practice and produce bugs that are incredibly hard to track down. **Rule of thumb**: if the struct crosses the Zig-C boundary in either direction, make it `extern struct`. No exceptions. Even if the layouts happen to match today, the Zig compiler makes no promises about regular struct layout between versions. ## Callback functions: passing Zig function pointers to C We touched on this earlier, but callbacks deserve a dedicated section because they're one of the most common patterns in C library design. The C library defines a function pointer type, you provide a Zig function that matches, and C calls it at the appropriate time. Event handlers, comparators, iterators, progress callbacks -- they're everywhere. ```zig const std = @import("std"); const c = @cImport({ @cInclude("stdlib.h"); }); // A C library might define something like: // typedef int (*transform_fn)(int value, void* user_data); // void apply_transform(int* arr, size_t len, transform_fn fn, void* user_data); // We can implement that pattern entirely in Zig: const TransformFn = *const fn (c_int, ?*anyopaque) callconv(.c) c_int; export fn applyTransform( arr: [*]c_int, len: usize, transform: TransformFn, user_data: ?*anyopaque, ) void { for (0..len) |i| { arr[i] = transform(arr[i], user_data); } } // Example callback: multiply by a factor stored in user_data fn multiplyCallback(value: c_int, user_data: ?*anyopaque) callconv(.c) c_int { const factor: *const c_int = @ptrCast(@alignCast(user_data.?)); return value * factor.*; } // Example callback: clamp to a range const ClampRange = extern struct { min_val: c_int, max_val: c_int, }; fn clampCallback(value: c_int, user_data: ?*anyopaque) callconv(.c) c_int { const range: *const ClampRange = @ptrCast(@alignCast(user_data.?)); if (value < range.min_val) return range.min_val; if (value > range.max_val) return range.max_val; return value; } pub fn main() void { var data = [_]c_int{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; // Multiply everything by 3 var factor: c_int = 3; applyTransform(&data, data.len, &multiplyCallback, @ptrCast(&factor)); std.debug.print("After multiply: ", .{}); for (data) |v| std.debug.print("{d} ", .{v}); std.debug.print("\n", .{}); // Clamp to [5, 20] var range = ClampRange{ .min_val = 5, .max_val = 20 }; applyTransform(&data, data.len, &clampCallback, @ptrCast(&range)); std.debug.print("After clamp: ", .{}); for (data) |v| std.debug.print("{d} ", .{v}); std.debug.print("\n", .{}); } ``` The `?*anyopaque` parameter is the classic C `void*` pattern for passing arbitrary context to callbacks. The callback casts it to whatever type it actually is. This is inherently unsafe -- if you pass the wrong type, you get undefined behavior. In pure Zig code you'd use generics and comptime to avoid this (as we covered in [episode 14](https://hive.blog/hive-196387/@scipio/learn-zig-series-14-generics-with-comptime-parameters)). But when talking to C, `void*` is the lingua franca. One pitfall: make sure the data that `user_data` points to outlives the callback. If you create a local variable and pass its address, then the callback gets called after the variable goes out of scope, you're reading garbage memory. In the example above, `factor` and `range` live on `main`'s stack for the entire duration of `applyTransform`, so it's safe. ## ABI considerations: alignment, padding, platform differences ABI stands for Application Binary Interface. It defines how functions are called at the machine level: which registers hold which arguments, how the stack is managed, how structs are passed and returned, alignment requirements, and more. When Zig and C code talk to each other, they must agree on the ABI. Here's what can go wrong and how to handle it: ```zig const std = @import("std"); // Alignment demonstration const AlignedData = extern struct { a: u8, // offset 0, size 1 // 3 bytes padding (b needs 4-byte alignment) b: u32, // offset 4, size 4 c: u8, // offset 8, size 1 // 1 byte padding (d needs 2-byte alignment) d: u16, // offset 10, size 2 // 0 bytes padding (e starts at offset 12, already 4-byte aligned) e: u32, // offset 12, size 4 // total: 16 bytes }; // If you need tighter packing, use packed struct const PackedData = packed struct { a: u8, b: u32, c: u8, d: u16, e: u32, // total: 12 bytes, no padding -- but NOT safe for C interop }; // Export a function that demonstrates struct sizes export fn getAlignedSize() usize { return @sizeOf(AlignedData); } pub fn main() void { std.debug.print("AlignedData:\n", .{}); std.debug.print(" size: {d} bytes\n", .{@sizeOf(AlignedData)}); std.debug.print(" align: {d} bytes\n", .{@alignOf(AlignedData)}); std.debug.print(" a offset: {d}\n", .{@offsetOf(AlignedData, "a")}); std.debug.print(" b offset: {d}\n", .{@offsetOf(AlignedData, "b")}); std.debug.print(" c offset: {d}\n", .{@offsetOf(AlignedData, "c")}); std.debug.print(" d offset: {d}\n", .{@offsetOf(AlignedData, "d")}); std.debug.print(" e offset: {d}\n", .{@offsetOf(AlignedData, "e")}); std.debug.print("\nPackedData:\n", .{}); std.debug.print(" size: {d} bytes\n", .{@sizeOf(PackedData)}); // Verify: these offsets must match what a C compiler produces // for: struct { uint8_t a; uint32_t b; uint8_t c; uint16_t d; uint32_t e; }; std.debug.print("\nLayout matches C? offsets a=0 b=4 c=8 d=10 e=12: {}\n", .{ @offsetOf(AlignedData, "a") == 0 and @offsetOf(AlignedData, "b") == 4 and @offsetOf(AlignedData, "c") == 8 and @offsetOf(AlignedData, "d") == 10 and @offsetOf(AlignedData, "e") == 12, }); } ``` The padding rules for `extern struct` follow the C standard: each field is aligned to its natural alignment (the size of the type, usually), and the struct's total size is a multiple of the largest field's alignment. This is why `AlignedData` is 16 bytes, not 12 -- there are gaps between `a` and `b`, and between `c` and `d`. A few things that commonly bite people on different platforms: - **`long` is 4 bytes on Windows x64 but 8 bytes on Linux x64**. Use `c_long` instead of `i64` or `i32` -- Zig picks the right size for the target. - **Struct return values**: some ABIs return small structs in registers, others on the stack. `extern struct` + `export fn` handles this correctly -- Zig follows the same ABI rules as the target's C compiler. - **Floating point**: x86_64 passes the first 8 float/double args in XMM registers (System V) or first 4 in XMM (Windows). Again, `callconv(.c)` handles this automaticaly. - **ARM vs x86**: completely different register conventions, stack growth direction, and alignment requirements. Zig's cross-compilation handles it, but be aware that a struct that works on your x86_64 dev machine might have different padding on ARM. ## Practical example: a Zig library usable from Python via ctypes Let's bring everything together with something genuinely useful. We'll write a small string processing library in Zig and call it from Python using ctypes. No C compiler involved at all -- Zig produces the shared library, Python loads it: ```zig // src/stringlib.zig const std = @import("std"); const StringStats = extern struct { length: u32, words: u32, lines: u32, uppercase: u32, lowercase: u32, digits: u32, }; export fn analyzeString(ptr: [*]const u8, len: u32) StringStats { const data = ptr[0..len]; var stats = StringStats{ .length = len, .words = 0, .lines = if (len > 0) @as(u32, 1) else 0, .uppercase = 0, .lowercase = 0, .digits = 0, }; var in_word = false; for (data) |ch| { if (ch >= 'A' and ch <= 'Z') { stats.uppercase += 1; if (!in_word) { stats.words += 1; in_word = true; } } else if (ch >= 'a' and ch <= 'z') { stats.lowercase += 1; if (!in_word) { stats.words += 1; in_word = true; } } else if (ch >= '0' and ch <= '9') { stats.digits += 1; if (!in_word) { stats.words += 1; in_word = true; } } else { in_word = false; if (ch == '\n') stats.lines += 1; } } return stats; } export fn rot13(ptr: [*]u8, len: u32) void { for (ptr[0..len]) |*ch| { if (ch.* >= 'A' and ch.* <= 'Z') { ch.* = 'A' + (ch.* - 'A' + 13) % 26; } else if (ch.* >= 'a' and ch.* <= 'z') { ch.* = 'a' + (ch.* - 'a' + 13) % 26; } } } export fn countSubstring( haystack_ptr: [*]const u8, haystack_len: u32, needle_ptr: [*]const u8, needle_len: u32, ) u32 { if (needle_len == 0 or needle_len > haystack_len) return 0; const haystack = haystack_ptr[0..haystack_len]; const needle = needle_ptr[0..needle_len]; var count: u32 = 0; var i: u32 = 0; while (i + needle_len <= haystack_len) : (i += 1) { if (std.mem.eql(u8, haystack[i .. i + needle_len], needle)) { count += 1; } } return count; } ``` Build it as a shared library with `zig build` (using the `build.zig` pattern from earlier, with `addSharedLibrary`). Then from Python: ```python # test_stringlib.py import ctypes import os # Load the shared library lib = ctypes.CDLL("./zig-out/lib/libstringlib.so") # Define the StringStats struct class StringStats(ctypes.Structure): _fields_ = [ ("length", ctypes.c_uint32), ("words", ctypes.c_uint32), ("lines", ctypes.c_uint32), ("uppercase", ctypes.c_uint32), ("lowercase", ctypes.c_uint32), ("digits", ctypes.c_uint32), ] # Set up function signatures lib.analyzeString.argtypes = [ctypes.c_char_p, ctypes.c_uint32] lib.analyzeString.restype = StringStats lib.rot13.argtypes = [ctypes.c_char_p, ctypes.c_uint32] lib.rot13.restype = None lib.countSubstring.argtypes = [ ctypes.c_char_p, ctypes.c_uint32, ctypes.c_char_p, ctypes.c_uint32, ] lib.countSubstring.restype = ctypes.c_uint32 # Test analyzeString text = b"Hello World!\nThis has 5 lines\nAnd UPPERCASE too\n42 numbers\nDone." stats = lib.analyzeString(text, len(text)) print(f"Length: {stats.length}") print(f"Words: {stats.words}") print(f"Lines: {stats.lines}") print(f"Uppercase: {stats.uppercase}") print(f"Lowercase: {stats.lowercase}") print(f"Digits: {stats.digits}") # Test rot13 msg = ctypes.create_string_buffer(b"Hello World") lib.rot13(msg, len(b"Hello World")) print(f"\nROT13: {msg.value.decode()}") # Apply rot13 again to get back original lib.rot13(msg, len(b"Hello World")) print(f"Back: {msg.value.decode()}") # Test countSubstring haystack = b"abcabcabc" needle = b"abc" count = lib.countSubstring(haystack, len(haystack), needle, len(needle)) print(f"\n'{needle.decode()}' appears {count} times in '{haystack.decode()}'") ``` This works because Python's ctypes speaks the C ABI directly. It loads the shared library, looks up symbols by name (the names we `export`ed), and calls them using the C calling convention. The `StringStats` struct in Python must match the `extern struct` layout in Zig exactly -- same field types, same order, same sizes. If they don't match, you get corrupt data. This pattern -- Zig library with exported C-ABI functions, consumed via FFI -- works with practically any language. Ruby has `fiddle` and `ffi`, Node.js has `node-ffi-napi`, Go has `cgo`, Rust has `extern "C"`. Your Zig library becomes a universal component. Having said that, there's an important limitation: error handling. Zig's error unions can't cross the C boundary. You can't return `!void` from an exported function -- C doesn't understand Zig error types. Instead, return status codes (`c_int` with 0 = success, negative = error) or use output parameters. Same for slices -- C doesn't have Zig slices, so you pass pointer + length separately, as we did in the examples above. ## Wat we geleerd hebben - The **`export`** keyword makes Zig functions visible to C with stable, unmangled symbol names. It also implies `callconv(.c)` -- the C calling convention. - **`callconv(.c)`** without `export` is for callback functions -- Zig functions that C calls through function pointers, not by name. - **Static and shared libraries** are built with `addStaticLibrary` and `addSharedLibrary` in `build.zig`. Static libs get linked into the final binary; shared libs are loaded at runtime. - **`extern struct`** guarantees C-compatible memory layout: fields in declaration order with standard padding. Regular Zig structs offer no such guarantee and MUST NOT cross the C boundary. - **Callback functions** use `callconv(.c)` with `?*anyopaque` as the universal context parameter (C's `void*` pattern). Make sure the pointed-to data outlives the callback. - **ABI rules** differ across platforms: `long` size, struct return conventions, register usage, alignment requirements. Using `extern struct` and `callconv(.c)` handles these differences automaticaly -- Zig follows the target platform's C ABI. - **The Python ctypes example** demonstrates the real power: Zig produces a shared library that any language with C FFI can call. No C compiler needed. No bindings generator. Just `export fn` and build. The interop story in Zig is genuinely best-in-class for systems languages. In episode 27 we called C from Zig (consuming existing C ecosystems), and today we exposed Zig to C (letting C and other languages consume our Zig code). Together, these two directions mean Zig plays nicely with the entire existing software ecosystem -- you can adopt it incrementally, one module at a time, without rewriting everything. For systems-level work involving memory-mapped I/O, hardware registers, and bare-metal control, that incremental adoption becomes even more powerful. ## Exercises 1. Write a Zig shared library that exports a `RingBuffer` implementation. Export functions `ringbuf_create(capacity: u32) -> *anyopaque`, `ringbuf_push(buf: *anyopaque, value: i32) -> bool`, `ringbuf_pop(buf: *anyopaque, out: *i32) -> bool`, and `ringbuf_destroy(buf: *anyopaque)`. The ring buffer should use a fixed-size backing array allocated with `std.heap.page_allocator`. Write a C program (or Python ctypes script) that creates a ring buffer, pushes 10 values, pops 5, pushes 5 more, then pops until empty. 2. Create a Zig library that exports a custom sorting function. Export `zig_sort(arr: [*]i32, len: usize, ascending: bool)` that sorts an integer array either ascending or descending based on the flag. Also export `zig_is_sorted(arr: [*]const i32, len: usize, ascending: bool) -> bool` that checks if an array is already sorted. Write a test program in C that creates several arrays, sorts them, and verifies with `zig_is_sorted`. 3. Build a Zig shared library that implements a simple "calculator protocol" using `extern struct` for communication. Define `CalcRequest` with fields `op: u8` ('+', '-', '*', '/'), `a: f64`, `b: f64` and `CalcResult` with fields `value: f64`, `error_code: i32` (0 = ok, 1 = division by zero, 2 = unknown op). Export `calc_execute(request: *const CalcRequest) -> CalcResult`. Then write a Python ctypes script that sends 5 different calculation requests and prints each result, including proper error handling for division by zero. Bedankt en tot de volgende keer! @scipio