std.os.linux.syscall and the syscall ABI (registers, return values, errno encoding);std.posix wrappers compare to raw syscalls and when you'd choose one over the other;Learn Zig Series):Exercise 1: Resource limit enforcer that reads limits from a config file
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const Rlimit = extern struct { cur: u64, max: u64 };
const LimitSpec = struct {
resource: u32,
value: u64,
};
fn parseSuffix(raw: []const u8) !u64 {
if (raw.len == 0) return error.EmptyValue;
const last = raw[raw.len - 1];
if (last == 'K' or last == 'k') {
return (try std.fmt.parseInt(u64, raw[0 .. raw.len - 1], 10)) * 1024;
} else if (last == 'M' or last == 'm') {
return (try std.fmt.parseInt(u64, raw[0 .. raw.len - 1], 10)) * 1024 * 1024;
} else if (last == 'G' or last == 'g') {
return (try std.fmt.parseInt(u64, raw[0 .. raw.len - 1], 10)) * 1024 * 1024 * 1024;
}
return try std.fmt.parseInt(u64, raw, 10);
}
fn resourceFromName(name: []const u8) ?u32 {
if (std.mem.eql(u8, name, "NOFILE")) return 7;
if (std.mem.eql(u8, name, "AS")) return 9;
if (std.mem.eql(u8, name, "CPU")) return 0;
if (std.mem.eql(u8, name, "CORE")) return 4;
if (std.mem.eql(u8, name, "NPROC")) return 6;
if (std.mem.eql(u8, name, "FSIZE")) return 1;
if (std.mem.eql(u8, name, "STACK")) return 3;
if (std.mem.eql(u8, name, "DATA")) return 2;
return null;
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
var args = std.process.args();
_ = args.next(); // skip program name
const config_path = args.next() orelse {
try stdout.print("Usage: rlimit_enforcer [args...]\n", .{});
return;
};
const target_program = args.next() orelse {
try stdout.print("Error: no target program specified\n", .{});
return;
};
_ = target_program;
// parse config
var file = try std.fs.cwd().openFile(config_path, .{});
defer file.close();
var buf: [4096]u8 = undefined;
const n = try file.readAll(&buf);
var lines = std.mem.splitScalar(u8, buf[0..n], '\n');
var limits: [16]LimitSpec = undefined;
var limit_count: usize = 0;
while (lines.next()) |line| {
const trimmed = std.mem.trim(u8, line, " \t\r");
if (trimmed.len == 0 or trimmed[0] == '#') continue;
var parts = std.mem.splitScalar(u8, trimmed, ' ');
const name = parts.next() orelse continue;
const val_str = parts.next() orelse continue;
const res = resourceFromName(name) orelse continue;
const val = parseSuffix(val_str) catch continue;
limits[limit_count] = .{ .resource = res, .value = val };
limit_count += 1;
}
// apply limits
for (limits[0..limit_count]) |spec| {
const rlim = Rlimit{ .cur = spec.value, .max = spec.value };
_ = linux.syscall2(.setrlimit, spec.resource, @intFromPtr(&rlim));
}
try stdout.print("Applied {d} resource limits from {s}\n", .{ limit_count, config_path });
}
The key insight is parsing the suffix multipliers (K/M/G) before converting to raw bytes. The setrlimit call sets both soft and hard to the same value -- that's the strictest enforcement possible, preventing the child from raising its own limit.
Exercise 2: Capability inspector reading /proc//status
const std = @import("std");
const cap_names = [_][]const u8{
"CAP_CHOWN", "CAP_DAC_OVERRIDE", "CAP_DAC_READ_SEARCH",
"CAP_FOWNER", "CAP_FSETID", "CAP_KILL",
"CAP_SETGID", "CAP_SETUID", "CAP_SETPCAP",
"CAP_LINUX_IMMUTABLE", "CAP_NET_BIND_SERVICE", "CAP_NET_BROADCAST",
"CAP_NET_ADMIN", "CAP_NET_RAW", "CAP_IPC_LOCK",
"CAP_IPC_OWNER", "CAP_SYS_MODULE", "CAP_SYS_RAWIO",
"CAP_SYS_CHROOT", "CAP_SYS_PTRACE", "CAP_SYS_PACCT",
"CAP_SYS_ADMIN", "CAP_SYS_BOOT", "CAP_SYS_NICE",
"CAP_SYS_RESOURCE", "CAP_SYS_TIME", "CAP_SYS_TTY_CONFIG",
"CAP_MKNOD", "CAP_LEASE", "CAP_AUDIT_WRITE",
"CAP_AUDIT_CONTROL", "CAP_SETFCAP", "CAP_MAC_OVERRIDE",
"CAP_MAC_ADMIN", "CAP_SYSLOG", "CAP_WAKE_ALARM",
"CAP_BLOCK_SUSPEND", "CAP_AUDIT_READ", "CAP_PERFMON",
"CAP_BPF", "CAP_CHECKPOINT_RESTORE",
};
fn decodeCaps(hex: []const u8) !u64 {
return try std.fmt.parseInt(u64, std.mem.trim(u8, hex, " \t\r\n"), 16);
}
fn printCaps(writer: anytype, label: []const u8, bitmask: u64) !void {
try writer.print(" {s}:\n", .{label});
var found: u32 = 0;
for (cap_names, 0..) |name, i| {
if ((bitmask >> @intCast(i)) & 1 == 1) {
try writer.print(" [{d:>2}] {s}\n", .{ i, name });
found += 1;
}
}
if (found == 0) try writer.print(" (none)\n", .{});
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
var args = std.process.args();
_ = args.next();
const pid_str = args.next() orelse "self";
var path_buf: [64]u8 = undefined;
const path = try std.fmt.bufPrint(&path_buf, "/proc/{s}/status", .{pid_str});
var file = std.fs.cwd().openFile(path, .{}) catch |err| {
try stdout.print("Cannot open {s}: {s}\n", .{ path, @errorName(err) });
return;
};
defer file.close();
var buf: [8192]u8 = undefined;
const n = try file.readAll(&buf);
var lines = std.mem.splitScalar(u8, buf[0..n], '\n');
var cap_prm: u64 = 0;
var cap_eff: u64 = 0;
var cap_bnd: u64 = 0;
while (lines.next()) |line| {
if (std.mem.startsWith(u8, line, "CapPrm:")) {
cap_prm = decodeCaps(line[7..]) catch 0;
} else if (std.mem.startsWith(u8, line, "CapEff:")) {
cap_eff = decodeCaps(line[7..]) catch 0;
} else if (std.mem.startsWith(u8, line, "CapBnd:")) {
cap_bnd = decodeCaps(line[7..]) catch 0;
}
}
try stdout.print("Capabilities for PID {s}:\n\n", .{pid_str});
try printCaps(stdout, "Permitted (CapPrm)", cap_prm);
try printCaps(stdout, "Effective (CapEff)", cap_eff);
try printCaps(stdout, "Bounding (CapBnd)", cap_bnd);
}
The /proc/<pid>/status file contains hex-encoded bitmasks where each bit position corresponds to a capability number. Decoding is straightforward -- parse the hex, then test each bit.
Exercise 3: Process jail combining three isolation layers
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
const Rlimit = extern struct { cur: u64, max: u64 };
const PR_SET_NO_NEW_PRIVS: u32 = 38;
fn setrlimit(resource: u32, rlim: Rlimit) void {
_ = linux.syscall2(.setrlimit, resource, @intFromPtr(&rlim));
}
fn runJailed() !void {
const stdout = std.io.getStdOut().writer();
// layer 1: resource limits
setrlimit(7, .{ .cur = 32, .max = 32 }); // NOFILE
setrlimit(9, .{ .cur = 64 * 1024 * 1024, .max = 64 * 1024 * 1024 }); // AS = 64MB
setrlimit(0, .{ .cur = 5, .max = 5 }); // CPU = 5s
setrlimit(6, .{ .cur = 2, .max = 2 }); // NPROC = 2
// layer 2: no new privs
_ = linux.syscall5(.prctl, PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0);
try stdout.print("[jail] All layers applied. Testing:\n", .{});
// test A: open 50 files
var opened: u32 = 0;
for (0..50) |_| {
_ = posix.open("/dev/null", .{ .ACCMODE = .RDONLY }, 0) catch break;
opened += 1;
}
try stdout.print(" Files opened: {d}/50 (blocked by RLIMIT_NOFILE)\n", .{opened});
// test B: allocate 100MB
var chunks: u32 = 0;
for (0..25) |_| { // 25 * 4MB = 100MB attempted
const result = linux.mmap(null, 4 * 1024 * 1024,
linux.PROT.READ | linux.PROT.WRITE,
.{ .TYPE = .PRIVATE, .ANONYMOUS = true }, -1, 0);
const signed: isize = @bitCast(result);
if (signed < 0) break;
chunks += 1;
}
try stdout.print(" Memory 4MB chunks: {d}/25 (blocked by RLIMIT_AS)\n", .{chunks});
// test C: fork 5 grandchildren
var forks: u32 = 0;
for (0..5) |_| {
const pid = posix.fork() catch break;
if (pid == 0) posix.exit(0);
_ = posix.waitpid(pid, 0);
forks += 1;
}
try stdout.print(" Forks succeeded: {d}/5 (blocked by RLIMIT_NPROC)\n", .{forks});
// test D: write to read-only path
const write_ok = if (std.fs.cwd().createFile("/proc/self/status", .{})) |f| blk: {
f.close();
break :blk true;
} else |_| false;
try stdout.print(" Write to /proc: {s}\n", .{if (write_ok) "allowed (bad!)" else "blocked (good)"});
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
try stdout.print("Process jail demo -- forking jailed child\n\n", .{});
const pid = try posix.fork();
if (pid == 0) {
runJailed() catch |err| {
std.debug.print("Jail error: {s}\n", .{@errorName(err)});
};
posix.exit(0);
}
const result = posix.waitpid(pid, 0);
const status = result.status;
if (status.signal()) |sig| {
try stdout.print("\nChild killed by signal {d}\n", .{@intFromEnum(sig)});
} else {
try stdout.print("\nChild exited with code {d}\n", .{status.exit_status()});
}
}
The three layers stack independently: rlimits block resource consumption, PR_SET_NO_NEW_PRIVS prevents privilege escalation through exec, and the read-only filesystem paths prevent unauthorized writes. Each layer catches different attack vectors.
We've spent the last several episodes building on top of what Zig's standard library gives us -- posix.fork(), posix.open(), posix.read(). But have you ever wondered what happens UNDERNEATH those nice wrapper functions? When you call posix.open(), how does your program actually talk to the kernel?
The answer is system calls -- and today we're going to peel back that layer entirely. We'll make raw syscalls by hand, understand the ABI (Application Binary Interface) that defines how arguments move between registers, and then build our own type-safe wrappers. By the end of this episode you'll understand exactly what happens at the boundary between your code and the Linux kernel ;-)
Your program runs in userspace. The kernel runs in kernel space. These are different privilege levels enforced by the CPU hardware itself (ring 3 vs ring 0 on x86). Your program cannot directly access hardware, manage memory pages, or talk to devices -- it must ASK the kernel to do these things on its behalf.
A system call is that request mechanism. It's a controlled transfer from userspace to kernel space. On x86-64 Linux, the instruction is syscall (literally -- that's the assembly mnemonic). The kernel has a table of ~450 numbered functions, and you invoke them by number.
Here's the thing that surprises people coming from higher-level languages: EVERYTHING your program does that involves the outside world goes through a syscall. Opening files? open() syscall. Reading bytes? read() syscall. Allocating memory? mmap() syscall. Sending a network packet? sendto() syscall. Even exit() is a syscall -- your program cannot terminate without the kernel's involvement.
const std = @import("std");
const linux = std.os.linux;
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
// every one of these uses syscalls internally:
// stdout.print -> write(1, buf, len) syscall
// std.time.timestamp -> clock_gettime syscall
// std.process.getEnvMap -> reads /proc/self/environ (open + read syscalls)
// std.posix.fork -> clone syscall
try stdout.print("System call numbers (x86-64 Linux):\n\n", .{});
const syscalls = [_]struct { num: u32, name: []const u8 }{
.{ .num = 0, .name = "read" },
.{ .num = 1, .name = "write" },
.{ .num = 2, .name = "open" },
.{ .num = 3, .name = "close" },
.{ .num = 9, .name = "mmap" },
.{ .num = 39, .name = "getpid" },
.{ .num = 56, .name = "clone" },
.{ .num = 57, .name = "fork" },
.{ .num = 59, .name = "execve" },
.{ .num = 60, .name = "exit" },
.{ .num = 62, .name = "kill" },
.{ .num = 228, .name = "clock_gettime" },
.{ .num = 318, .name = "getrandom" },
.{ .num = 319, .name = "memfd_create" },
};
for (syscalls) |sc| {
try stdout.print(" {d:>3}: {s}\n", .{ sc.num, sc.name });
}
try stdout.print("\nTotal syscalls in Linux 6.x: ~450\n", .{});
try stdout.print("Zig exposes them via std.os.linux.SYS enum\n", .{});
}
The numbers are stable -- Linux guarantees that syscall numbers never change for a given architecture. That's the whole point: it's a stable ABI. Userspace binaries compiled 20 years ago still work because syscall 1 is still write and syscall 2 is still open. This stability is a fundamental design principle of Linux.
Zig gives you direct access to the syscall instruction through std.os.linux.syscall0 through syscall6 (the number indicates how many arguments). These are NOT wrappers -- they compile down to literally loading registers and executing the syscall instruction. Zero overhead, zero abstraction:
const std = @import("std");
const linux = std.os.linux;
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
// raw getpid -- no arguments
const pid = linux.syscall0(.getpid);
try stdout.print("PID (raw syscall): {d}\n", .{pid});
// raw write -- write(fd=1, buf, len)
const msg = "Hello from raw write syscall!\n";
const written = linux.syscall3(
.write,
1, // fd 1 = stdout
@intFromPtr(msg.ptr),
msg.len,
);
_ = written;
// raw getuid -- no arguments
const uid = linux.syscall0(.getuid);
try stdout.print("UID: {d}\n", .{uid});
// raw clock_gettime
var ts: linux.timespec = undefined;
const clock_result = linux.syscall2(
.clock_gettime,
0, // CLOCK_REALTIME
@intFromPtr(&ts),
);
const clock_signed: isize = @bitCast(clock_result);
if (clock_signed == 0) {
try stdout.print("Time: {d}.{d:0>9} seconds since epoch\n", .{
ts.sec, ts.nsec,
});
}
// raw uname
var uts: linux.utsname = undefined;
const uname_result = linux.syscall1(.uname, @intFromPtr(&uts));
const uname_signed: isize = @bitCast(uname_result);
if (uname_signed == 0) {
const sysname = std.mem.sliceTo(&uts.sysname, 0);
const release = std.mem.sliceTo(&uts.release, 0);
const machine = std.mem.sliceTo(&uts.machine, 0);
try stdout.print("System: {s} {s} ({s})\n", .{ sysname, release, machine });
}
}
Notice the pattern: every argument becomes a usize -- pointers get converted with @intFromPtr, integers pass directly. The return value is also a usize. This is the raw register-level interface. No types, no safety, no error handling. Just numbers going into registers and a number coming back.
On x86-64 Linux, the syscall convention is:
syscall)The return value in RAX is either the successful result OR a negative error code. The range -4095 to -1 indicates an error, where the absolute value is the errno. Everything else is success. This is different from the C library convention where errno is a separate thread-local variable:
const std = @import("std");
const linux = std.os.linux;
const E = linux.E;
fn syscallToError(result: usize) !usize {
const signed: isize = @bitCast(result);
if (signed >= -4095 and signed < 0) {
const errno: u16 = @intCast(@as(usize, @bitCast(-signed)));
return switch (errno) {
@intFromEnum(E.ACCES) => error.AccessDenied,
@intFromEnum(E.NOENT) => error.FileNotFound,
@intFromEnum(E.EXIST) => error.PathAlreadyExists,
@intFromEnum(E.INVAL) => error.InvalidArgument,
@intFromEnum(E.MFILE) => error.TooManyOpenFiles,
@intFromEnum(E.NOSYS) => error.SyscallNotSupported,
@intFromEnum(E.PERM) => error.PermissionDenied,
@intFromEnum(E.FAULT) => error.BadAddress,
else => error.Unexpected,
};
}
return result;
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
// successful call
const pid = try syscallToError(linux.syscall0(.getpid));
try stdout.print("getpid() = {d}\n", .{pid});
// call that will fail: open a nonexistent file
const result = linux.syscall3(
.open,
@intFromPtr("/tmp/definitely_not_a_real_file_xyz123".ptr),
0, // O_RDONLY
0,
);
const signed: isize = @bitCast(result);
try stdout.print("\nopen() returned: {d} (raw)\n", .{signed});
try stdout.print("Errno value: {d} (ENOENT = {d})\n", .{
@as(usize, @bitCast(-signed)),
@intFromEnum(E.NOENT),
});
// using our error conversion
_ = syscallToError(result) catch |err| {
try stdout.print("Converted to Zig error: {s}\n", .{@errorName(err)});
};
// another failure: invalid syscall number
const bad = linux.syscall0(@enumFromInt(99999));
const bad_signed: isize = @bitCast(bad);
try stdout.print("\nInvalid syscall returned: {d}\n", .{bad_signed});
try stdout.print("Errno: {d} (ENOSYS = {d})\n", .{
@as(usize, @bitCast(-bad_signed)),
@intFromEnum(E.NOSYS),
});
}
This is the fundamental contract between userspace and the kernel. The kernel NEVER raises a signal or throws an exception to indicate a syscall error (with the specific exception of SIGPIPE for write-to-closed-pipe, which is a different mechanism). It always returns a value in RAX, and the caller checks whether that value is in the error range. Zig's standard library does this check for you in std.posix, but when you go raw, you're responsible.
Now here's where Zig really shines. We can take these raw untyped register operations and wrap them in functions that have proper error sets, proper argument types, and proper return types. The compiler optimizes away all the wrapping -- you get safety at zero runtime cost:
const std = @import("std");
const linux = std.os.linux;
const SyscallError = error{
AccessDenied,
FileNotFound,
InvalidArgument,
TooManyOpenFiles,
PermissionDenied,
BadAddress,
Unexpected,
};
fn checkResult(result: usize) SyscallError!usize {
const signed: isize = @bitCast(result);
if (signed >= -4095 and signed < 0) {
const errno: u16 = @intCast(@as(usize, @bitCast(-signed)));
return switch (errno) {
13 => error.AccessDenied, // EACCES
2 => error.FileNotFound, // ENOENT
22 => error.InvalidArgument, // EINVAL
24 => error.TooManyOpenFiles,// EMFILE
1 => error.PermissionDenied, // EPERM
14 => error.BadAddress, // EFAULT
else => error.Unexpected,
};
}
return result;
}
// type-safe getpid wrapper
pub fn getpid() u32 {
return @intCast(linux.syscall0(.getpid));
}
// type-safe write wrapper
pub fn write(fd: i32, buf: []const u8) SyscallError!usize {
const result = linux.syscall3(
.write,
@as(usize, @bitCast(@as(isize, fd))),
@intFromPtr(buf.ptr),
buf.len,
);
return checkResult(result);
}
// type-safe close wrapper
pub fn close(fd: i32) SyscallError!void {
const result = linux.syscall1(
.close,
@as(usize, @bitCast(@as(isize, fd))),
);
_ = try checkResult(result);
}
// type-safe dup2 wrapper
pub fn dup2(oldfd: i32, newfd: i32) SyscallError!i32 {
const result = linux.syscall2(
.dup2,
@as(usize, @bitCast(@as(isize, oldfd))),
@as(usize, @bitCast(@as(isize, newfd))),
);
return @intCast(@as(isize, @bitCast(try checkResult(result))));
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
const pid = getpid();
try stdout.print("PID: {d}\n", .{pid});
const msg = "Written via type-safe wrapper!\n";
const n = try write(1, msg);
try stdout.print("write() returned: {d} bytes\n", .{n});
// demonstrate error handling
write(-1, "bad fd") catch |err| {
try stdout.print("write(-1) error: {s}\n", .{@errorName(err)});
};
try stdout.print("\nThe wrapper adds type safety with zero runtime cost.\n", .{});
try stdout.print("In release mode, these compile to identical instructions.\n", .{});
}
The crucial design choice: separate error sets per wrapper vs one big global error set. In production code (like Zig's std library), each function has its own error set listing only the errors that function can actually return. This lets the compiler verify that callers handle all possible errors -- you can't forget one. Our simplified SyscallError above is a teaching shortcut; real wrappers would be more precise.
Every device driver in Linux has a different set of operations it supports -- terminal settings, disk geometry, network interface configuration, GPU commands. Rather than adding a new syscall for each one, Linux uses a single catchall: ioctl (input/output control). It takes a file descriptor, a request code, and an optional argument (usually a pointer to a struct):
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
// terminal ioctl constants
const TIOCGWINSZ: u32 = 0x5413; // get window size
const TIOCGPGRP: u32 = 0x540F; // get foreground process group
const TCGETS: u32 = 0x5401; // get terminal attributes
const Winsize = extern struct {
ws_row: u16,
ws_col: u16,
ws_xpixel: u16,
ws_ypixel: u16,
};
const Termios = extern struct {
c_iflag: u32,
c_oflag: u32,
c_cflag: u32,
c_lflag: u32,
c_line: u8,
c_cc: [19]u8,
_padding: [3]u8 = .{ 0, 0, 0 },
c_ispeed: u32,
c_ospeed: u32,
};
fn ioctl(fd: i32, request: u32, arg: usize) isize {
const result = linux.syscall3(
.ioctl,
@as(usize, @bitCast(@as(isize, fd))),
request,
arg,
);
return @bitCast(result);
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
try stdout.print("ioctl demonstrations:\n\n", .{});
// get terminal window size
var ws: Winsize = undefined;
const ws_result = ioctl(1, TIOCGWINSZ, @intFromPtr(&ws));
if (ws_result == 0) {
try stdout.print("Terminal size: {d} rows x {d} cols", .{ ws.ws_row, ws.ws_col });
if (ws.ws_xpixel > 0) {
try stdout.print(" ({d}x{d} pixels)", .{ ws.ws_xpixel, ws.ws_ypixel });
}
try stdout.print("\n", .{});
} else {
try stdout.print("TIOCGWINSZ failed (not a terminal?)\n", .{});
}
// get foreground process group
var pgrp: i32 = 0;
const pgrp_result = ioctl(0, TIOCGPGRP, @intFromPtr(&pgrp));
if (pgrp_result == 0) {
try stdout.print("Foreground process group: {d}\n", .{pgrp});
}
// get terminal attributes
var tio: Termios = undefined;
const tio_result = ioctl(0, TCGETS, @intFromPtr(&tio));
if (tio_result == 0) {
try stdout.print("\nTerminal flags:\n", .{});
try stdout.print(" Input flags: 0x{x:0>8}\n", .{tio.c_iflag});
try stdout.print(" Output flags: 0x{x:0>8}\n", .{tio.c_oflag});
try stdout.print(" Control flags: 0x{x:0>8}\n", .{tio.c_cflag});
try stdout.print(" Local flags: 0x{x:0>8}\n", .{tio.c_lflag});
try stdout.print(" ECHO enabled: {s}\n", .{
if (tio.c_lflag & 0x8 != 0) "yes" else "no",
});
try stdout.print(" ICANON mode: {s}\n", .{
if (tio.c_lflag & 0x2 != 0) "yes (line buffered)" else "no (raw)",
});
}
try stdout.print("\nioctl request codes encode: direction, type, number, size\n", .{});
try stdout.print("TIOCGWINSZ = 0x{x}: 'T' type, GET direction, Winsize size\n", .{TIOCGWINSZ});
}
The request code (like TIOCGWINSZ = 0x5413) encodes four pieces of information: the direction (read/write/both), the device type (a character, like 'T' for terminal), a sequential number, and the size of the argument struct. This encoding lets the kernel validate ioctl calls before passing them to the driver. If you pass the wrong size, the kernel can catch it early insted of letting the driver read garbage.
The reason ioctl exists as one big multiplex syscall rather than hundreds of specific ones: adding a syscall is a HUGE deal in Linux (it becomes part of the stable ABI forever). Adding an ioctl command to a driver is trivial -- it's just a switch case in the driver code. So ioctl became the escape hatch for device-specific functionality that doesn't warrant a dedicated syscall.
When something goes wrong at the system call level -- a file that won't open, a socket that refuses to bind, a mysterious EINVAL -- strace is your best friend. It intercepts every syscall your program makes and prints the arguments and return values. Here's how to read its output and how to write code that's easy to trace:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
try stdout.print("Run this program with: strace -f ./program 2>trace.log\n", .{});
try stdout.print("Then examine trace.log to see every syscall.\n\n", .{});
// deliberate mix of successful and failing calls for strace demo
try stdout.print("Making various syscalls for strace to capture:\n", .{});
// 1. successful open + close
const fd = posix.open("/etc/hostname", .{ .ACCMODE = .RDONLY }, 0) catch |err| {
try stdout.print(" open /etc/hostname: {s}\n", .{@errorName(err)});
return;
};
try stdout.print(" opened /etc/hostname as fd {d}\n", .{fd});
var buf: [256]u8 = undefined;
const n = try posix.read(fd, &buf);
try stdout.print(" read {d} bytes: {s}", .{ n, buf[0..n] });
posix.close(fd);
// 2. failing open (no such file)
_ = posix.open("/tmp/nonexistent_strace_demo", .{ .ACCMODE = .RDONLY }, 0) catch |err| {
try stdout.print(" open nonexistent: {s} (strace shows ENOENT)\n", .{@errorName(err)});
};
// 3. getpid (always succeeds, useful as a marker in traces)
const pid = linux.syscall0(.getpid);
try stdout.print(" getpid = {d}\n", .{pid});
// 4. failing ioctl (bad fd)
const ioctl_result = linux.syscall3(.ioctl, 999, 0x5413, @intFromPtr(&buf));
const ioctl_signed: isize = @bitCast(ioctl_result);
try stdout.print(" ioctl(999, TIOCGWINSZ) = {d} (EBADF)\n", .{ioctl_signed});
try stdout.print("\nstrace output for this would look like:\n", .{});
try stdout.print(" openat(AT_FDCWD, \"/etc/hostname\", O_RDONLY) = 3\n", .{});
try stdout.print(" read(3, \"myhost\\n\", 256) = 7\n", .{});
try stdout.print(" close(3) = 0\n", .{});
try stdout.print(" openat(AT_FDCWD, \"/tmp/nonexistent_...\", O_RDONLY) = -1 ENOENT\n", .{});
try stdout.print(" getpid() = {d}\n", .{pid});
try stdout.print(" ioctl(999, TIOCGWINSZ, 0x...) = -1 EBADF\n", .{});
try stdout.print("\nUseful strace flags:\n", .{});
try stdout.print(" -e trace=open,read,write -- filter specific syscalls\n", .{});
try stdout.print(" -e trace=network -- only network syscalls\n", .{});
try stdout.print(" -e trace=file -- only file syscalls\n", .{});
try stdout.print(" -p PID -- attach to running process\n", .{});
try stdout.print(" -f -- follow forks\n", .{});
try stdout.print(" -t -- timestamps\n", .{});
try stdout.print(" -c -- count/summary mode\n", .{});
}
A pro tip: when debugging a complex program, insert a getpid() syscall as a "marker" before the problematic section. In the strace output you can search for getpid() to find exactly where in the trace to start reading. It's the syscall equivalent of a printf("HERE\n") debug statement ;-)
The -c flag gives you a syscall profile -- how many times each syscall was called and total time spent. Extremely useful for performance debugging. If your program is spending 80% of its time in futex(), you've got a contention problem. If it's all in read(), you might need buffering.
So when should you use std.posix.open() vs raw linux.syscall3(.open, ...)? The answer is almost always use the standard library -- but understanding the raw layer helps you debug issues and write wrappers for syscalls that Zig doesn't expose yet:
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
try stdout.print("Comparing std.posix wrappers vs raw syscalls:\n\n", .{});
// approach 1: std.posix (recommended)
{
const fd = try posix.open("/dev/null", .{ .ACCMODE = .WRONLY }, 0);
defer posix.close(fd);
_ = try posix.write(fd, "hello");
try stdout.print("[std.posix] open + write + close: OK\n", .{});
try stdout.print(" Pros: type-safe, cross-platform, proper error sets\n", .{});
try stdout.print(" Cons: limited to what std exposes\n", .{});
}
// approach 2: raw syscall (when you need it)
{
const result = linux.syscall3(
.openat,
@as(usize, @bitCast(@as(isize, linux.AT.FDCWD))),
@intFromPtr("/dev/null".ptr),
1, // O_WRONLY
);
const signed: isize = @bitCast(result);
if (signed < 0) {
try stdout.print("[raw] openat failed\n", .{});
} else {
const fd: i32 = @intCast(signed);
_ = linux.syscall3(.write, @as(usize, @bitCast(@as(isize, fd))), @intFromPtr("hello".ptr), 5);
_ = linux.syscall1(.close, @as(usize, @bitCast(@as(isize, fd))));
try stdout.print("[raw syscall] openat + write + close: OK\n", .{});
try stdout.print(" Pros: access ANY syscall, maximum control\n", .{});
try stdout.print(" Cons: no type safety, Linux-only, manual error check\n", .{});
}
}
try stdout.print("\nWhen to use raw syscalls:\n", .{});
try stdout.print(" - Syscall not exposed by std (memfd_create, io_uring_setup)\n", .{});
try stdout.print(" - Need exact control over flags/args\n", .{});
try stdout.print(" - Debugging what std is doing underneath\n", .{});
try stdout.print(" - Writing your own platform abstraction layer\n", .{});
try stdout.print(" - Performance-critical paths (avoid std overhead, if any)\n", .{});
try stdout.print("\nWhen to use std.posix:\n", .{});
try stdout.print(" - Everything else (99%% of the time)\n", .{});
try stdout.print(" - Cross-platform code (works on macOS/BSD too)\n", .{});
try stdout.print(" - Correct error handling out of the box\n", .{});
try stdout.print(" - Maintained and tested by the Zig team\n", .{});
// note: std.posix.open actually calls openat under the hood
// (open is deprecated in modern Linux, openat is the real call)
try stdout.print("\nFun fact: posix.open() calls openat(AT_FDCWD, ...) internally.\n", .{});
try stdout.print("The 'open' syscall is effectively deprecated in favor of openat.\n", .{});
}
Having said that, the performance difference is effectively zero. Zig's std.posix wrappers compile down to the exact same syscall instruction in release mode. The "overhead" is purely at compile time -- the type checking, error set narrowing, and cross-platform abstraction all disappear by the time machine code is generated. You use raw syscalls when std doesn't expose what you need, not for performance.
Let's build proper wrappers for two useful syscalls that demonstrate different patterns. getrandom fills a buffer with random bytes (the modern replacement for reading /dev/urandom). memfd_create creates an anonymous file backed by RAM (incredibly useful for passing data between processes without touching the filesystem):
const std = @import("std");
const linux = std.os.linux;
const posix = std.posix;
// --- getrandom wrapper ---
const GetrandomError = error{
WouldBlock, // EAGAIN with GRND_NONBLOCK
Interrupted, // EINTR (signal during read)
InvalidFlags, // EFAULT or EINVAL
Unexpected,
};
const GRND_NONBLOCK: u32 = 0x0001;
const GRND_RANDOM: u32 = 0x0002;
fn getrandom(buf: []u8, flags: u32) GetrandomError!usize {
const result = linux.syscall3(
.getrandom,
@intFromPtr(buf.ptr),
buf.len,
flags,
);
const signed: isize = @bitCast(result);
if (signed < 0) {
const errno: u32 = @intCast(@as(usize, @bitCast(-signed)));
return switch (errno) {
11 => error.WouldBlock, // EAGAIN
4 => error.Interrupted, // EINTR
14, 22 => error.InvalidFlags,
else => error.Unexpected,
};
}
return @intCast(signed);
}
// --- memfd_create wrapper ---
const MemfdError = error{
TooManyOpenFiles,
InvalidName,
PermissionDenied,
Unexpected,
};
const MFD_CLOEXEC: u32 = 0x0001;
const MFD_ALLOW_SEALING: u32 = 0x0002;
fn memfdCreate(name: [*:0]const u8, flags: u32) MemfdError!i32 {
const result = linux.syscall2(
.memfd_create,
@intFromPtr(name),
flags,
);
const signed: isize = @bitCast(result);
if (signed < 0) {
const errno: u32 = @intCast(@as(usize, @bitCast(-signed)));
return switch (errno) {
24 => error.TooManyOpenFiles, // EMFILE
22 => error.InvalidName, // EINVAL
1 => error.PermissionDenied, // EPERM
else => error.Unexpected,
};
}
return @intCast(signed);
}
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
// demonstrate getrandom
try stdout.print("getrandom() -- cryptographic random bytes:\n", .{});
var random_bytes: [32]u8 = undefined;
const got = try getrandom(&random_bytes, 0);
try stdout.print(" Requested 32, got {d} bytes: ", .{got});
for (random_bytes[0..16]) |b| {
try stdout.print("{x:0>2}", .{b});
}
try stdout.print("...\n", .{});
// demonstrate memfd_create
try stdout.print("\nmemfd_create() -- anonymous RAM-backed file:\n", .{});
const memfd = try memfdCreate("my_shared_buffer", MFD_CLOEXEC);
try stdout.print(" Created memfd: fd={d}\n", .{memfd});
// write data to it
const data = "This data lives in RAM, not on disk!";
_ = try posix.write(memfd, data);
try stdout.print(" Wrote {d} bytes to memfd\n", .{data.len});
// seek back and read it
_ = linux.syscall3(.lseek, @as(usize, @bitCast(@as(isize, memfd))), 0, 0);
var read_buf: [128]u8 = undefined;
const n = try posix.read(memfd, &read_buf);
try stdout.print(" Read back: \"{s}\"\n", .{read_buf[0..n]});
// show it exists in /proc
var link_buf: [128]u8 = undefined;
var proc_path_buf: [64]u8 = undefined;
const proc_path = try std.fmt.bufPrint(&proc_path_buf, "/proc/self/fd/{d}", .{memfd});
const link = posix.readlink(proc_path, &link_buf) catch "(unreadable)";
try stdout.print(" /proc link: {s}\n", .{link});
// resize it (ftruncate works on memfds)
_ = linux.syscall2(.ftruncate, @as(usize, @bitCast(@as(isize, memfd))), 4096);
try stdout.print(" Resized to 4096 bytes\n", .{});
posix.close(memfd);
try stdout.print(" Closed -- memory freed, no filesystem cleanup needed.\n", .{});
try stdout.print("\nUse cases for memfd_create:\n", .{});
try stdout.print(" - Shared memory between parent/child (pass fd over fork)\n", .{});
try stdout.print(" - Temporary buffers without /tmp pollution\n", .{});
try stdout.print(" - Loading code for JIT (memfd + exec permissions)\n", .{});
try stdout.print(" - Sealed memory regions (immutable shared data)\n", .{});
}
The getrandom wrapper is interesting because it can be interrupted by signals (returning EINTR) and can fail if the entropy pool isn't ready yet (EAGAIN with GRND_NONBLOCK). A robust implementation would retry on EINTR and loop until the full buffer is filled -- just like read() on a regular file might return fewer bytes than requested.
The memfd_create wrapper shows a different pattern: it creates a resource (returns an fd) rather than performing an action. The MFD_CLOEXEC flag ensures the fd is automatically closed if the process exec's a new program -- this prevents fd leaks into child processes, which is a common security issue.
Implement a syscall tracer that uses PTRACE_SYSCALL to intercept and log all syscalls made by a child process. Fork a child, attach to it with ptrace, then for each syscall entry/exit event, read the syscall number from the child's registers (using PTRACE_GETREGS) and print the syscall name and return value. Run it on a simple program like /bin/ls and print a summary of which syscalls were called and how many times each. This is a simplified version of what strace does internally.
Write a safe ioctl wrapper library that provides type-safe wrappers for the three terminal ioctls: TIOCGWINSZ (get window size), TIOCSWINSZ (set window size), and TCGETS/TCSETS (get/set terminal attributes). Each wrapper should take properly typed arguments (Winsize struct, Termios struct) and return proper Zig error sets. Include a function that puts the terminal into raw mode (disable ECHO and ICANON), reads a single keypress, then restores the original settings. Handle the case where stdin is not a terminal (piped input).
Build a memfd-based IPC channel using your memfd_create wrapper. The parent creates a memfd, writes a message struct (with a sequence number, timestamp, and payload), then forks a child. The child inherits the fd, mmaps it, reads the message, modifies the sequence number, and writes a response. The parent then reads the child's response. Implement proper synchronization using a futex (another raw syscall) in the shared memory region so the parent waits for the child to finish writing before reading. This demonstrates memfd + mmap + futex as a zero-copy IPC mechanism.
std.os.linux.syscall0 through syscall6 -- these compile to literal syscall instructions with zero overheadstd.posix wrappers handle error translation and cross-platform differences -- use them by default, go raw only when std doesn't expose the syscall you need
@scipio