liveBook · Manning

C ABI compatibility

As explained in Systems Programming with Zig

The C ABI is the platform-specific binary interface convention commonly designed around the C language's stable data representation and expected by a computer system's operating system and CPU.

A Zig library can manage recipe data while a PHP frontend handles the interface, but the two need a common way to communicate. The C ABI supplies that boundary: rules for exposing functions and data so code built with different languages and compilers can work together. section 5.0 section 5.2 section 5.7

There is no single C ABI for every machine. The relevant rules depend on the operating system and CPU and are designed around C’s simple, stable data representation. Compilers do most of the work of following them; you do not need to be a C expert to use the interface. section 5.2.1

In Zig, make the boundary explicit:

  • Declare a C-compatible structure as `extern struct`. Ordinary Zig structs do not have a guaranteed memory layout, while the C ABI requires one. section 5.2.2
  • Use `export` for functions that must be available from a library. For C integer parameters and fields, use types such as `c_int` or `c_long`, whose widths can vary by environment. section 5.2.2
  • Pass pointers to internal data when the data itself is not ABI-compatible. Use regular functions in place of method syntax; the C ABI does not provide namespaces or methods. section 5.2.2 section 5.3.1
  • For a C-compatible callback that need not be exported, specify `callconv(.c)` between the parameters and return type. section 7.3.2

Zig conveniences such as errors and slices do not have a good general translation to the C ABI. At the boundary, choose a simpler representation and document its meaning. For example, a nullable pointer can signal that creation failed. If a type’s compatibility is unclear, try compiling and let the compiler report the problem. section 5.2.2 section 5.4

Listing 5.3 An object without methods
const std = @import("std");

var gpa: std.heap.SafeAllocator(.{}) = .init; #1
var threaded: std.Io.Threaded = .init_single_threaded;

export fn recipes_quit() void {
    _ = gpa.deinit(); #2
    threaded.deinit();
    gpa = .init; #3
    threaded = .init_single_threaded;
}

const RecipeBook = struct {}; #4

export fn recipe_book_create() ?*RecipeBook { #5
    const ally = gpa.allocator();
    const book = ally.create(RecipeBook) catch {
        return null; #6
    };
    book.* = .{}; #7
    return book;
}

export fn recipe_book_close(book: *RecipeBook) void { #8
    const ally = gpa.allocator();
    book.deinit(ally); #9
    ally.destroy(book);
}

The recipe library exports create and close functions around a pointer to its internal object. Creation returns null on allocation failure; closing destroys the object. A separate quit function releases library-wide resources. section 5.3.1 section 5.4

Listing 7.5 Error callback
fn glfwErrorCallback(code: c_int, desc: [*c]const u8)
callconv(.c) void { #1
    std.debug.print("glfw error {d}: {s}\n", .{ code, desc }); #2
}

pub fn main() !void {
    // ... call glfwInit ...

    _ = c.glfwSetErrorCallback(&glfwErrorCallback); #3

    // ... the rest of the code ...
}

This GLFW error callback uses `callconv(.c)` to match the expected calling convention without exporting the function as a library entry point. section 7.3.2

How Systems Programming with Zig covers it

How deep it goes
Explains platform dependence and Zig interface annotations, including layout, integer types, pointers, errors, and calling conventions.
Examples
Uses a recipe library’s create and close functions and a GLFW error callback.
What it assumes
Explains the ABI without requiring expert C programming, relying on compilers to handle much of the work.
What you can do after
Apply it via Zig to expose library functions and write C-compatible callbacks.
How it connects
Connects foreign function interfaces with data layout, calling conventions, error handling, and resource management.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Systems Programming with Zig. The section links point to the parts of the book it draws on.