From 3fdb67c479dcc1ad0f1e51832bc086622692249c Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 11:43:24 -0300 Subject: debugger: steps by instruction and line, breakpoints, hooks, watches, threads; ztrace dbg ptrace.zig follows the threads a target makes, attaches, tells a step from a breakpoint, and writes memory in one call (through /proc/pid/mem where the page is read-only). Debugger.zig is the layer above: cont, stepi, step (a source line, through std.debug's DWARF), breakpoints with hooks, syscall stops and hooks with the path or buffer captured, watched regions sent as the words that changed, and every stop an event. Symbols.zig is modules, ELF symbols and line tables; syscalls.zig their names and shapes. ztrace dbg is a small REPL on it that records as it goes and looks back into the recording; ztrace record stops by instruction, line, syscall or breakpoint, prints syscalls as strace does, and ends cleanly when the recording is full. Co-Authored-By: Claude Fable 5.2 --- src/trace/syscalls.zig | 141 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 src/trace/syscalls.zig (limited to 'src/trace/syscalls.zig') diff --git a/src/trace/syscalls.zig b/src/trace/syscalls.zig new file mode 100644 index 0000000..2bf32b5 --- /dev/null +++ b/src/trace/syscalls.zig @@ -0,0 +1,141 @@ +//! x86-64 syscalls by number: their names from `std.os.linux.SYS`, and for +//! the common ones the shape of their arguments, enough to capture the +//! string one points at and to print a call the way strace does. +const std = @import("std"); +const linux = std.os.linux; +const event = @import("event.zig"); +const Event = event.Event; + +pub fn name(nr: u64) ?[]const u8 { + return @tagName(std.enums.fromInt(linux.SYS, nr) orelse return null); +} + +/// A letter an argument: i an int (a descriptor, a pid, a signal), d a +/// size, x a pointer or flags, s a NUL-terminated string, b a buffer as long +/// as the next argument says. Six x for a syscall not listed. +pub fn signature(nr: u64) []const u8 { + return switch (std.enums.fromInt(linux.SYS, nr) orelse return "xxxxxx") { + .getpid, .gettid, .getppid, .getuid, .geteuid, .getgid, .getegid, .sched_yield, .pause, .fork, .vfork => "", + .close, .exit, .exit_group, .dup, .fsync => "i", + .brk, .set_tid_address, .uname, .pipe, .time => "x", + .chdir, .rmdir, .unlink => "s", + .read, .readv, .writev, .getdents64 => "ixd", + .write => "ibd", + .pread64 => "ixdd", + .pwrite64 => "ibdd", + .open => "sxx", + .stat, .lstat, .access, .chmod, .mkdir => "sx", + .execve => "sxx", + .fstat => "ix", + .lseek => "idi", + .mmap => "xdxxid", + .mprotect => "xdx", + .munmap, .set_robust_list, .getcwd => "xd", + .mremap => "xddxx", + .madvise => "xdi", + .rt_sigaction, .rt_sigprocmask => "ixxd", + .ioctl, .fcntl => "ixx", + .dup2, .kill => "ii", + .tgkill => "iii", + .rename => "ss", + .readlink => "sxd", + .arch_prctl, .nanosleep, .sigaltstack => "xx", + .futex => "xiixxi", + .clock_gettime, .clock_getres => "ix", + .clock_nanosleep => "iixx", + .openat, .newfstatat, .faccessat2 => "isxx", + .unlinkat, .faccessat, .mkdirat => "isx", + .readlinkat => "isxd", + .statx => "isxxx", + .prlimit64 => "iixx", + .getrandom => "xdx", + .rseq => "xdxx", + .clone => "xxxxx", + .clone3 => "xd", + .wait4 => "ixxx", + .sched_getaffinity => "idx", + else => "xxxxxx", + }; +} + +/// A call the way strace prints it, from a `syscall_enter` event and its +/// payload: `openat(-100, "/etc/passwd", 0x80000, 0x0)`. +pub fn formatEnter(w: *std.Io.Writer, ev: *const Event, payload: []const u8) !void { + if (name(ev.aux)) |n| try w.writeAll(n) else try w.print("syscall_{d}", .{ev.aux}); + try w.writeAll("("); + // The payload is the first string or buffer, decoded; the registers when there was none to read. + var decoded: ?[]const u8 = if (payload.len == @sizeOf(event.Regs)) null else payload; + for (signature(ev.aux), 0..) |kind, i| { + if (i > 0) try w.writeAll(", "); + switch (kind) { + 'i' => try w.print("{d}", .{@as(i32, @bitCast(@as(u32, @truncate(ev.a[i]))))}), + 'd' => try w.print("{d}", .{ev.a[i]}), + 's', 'b' => if (decoded) |text| { + // Dots, as strace has them, when the buffer was longer than what was captured. + try w.print("\"{f}\"{s}", .{ std.zig.fmtString(text), if (kind == 'b' and text.len < ev.a[i + 1]) "..." else "" }); + decoded = null; + } else try w.print("0x{x}", .{ev.a[i]}), + else => try w.print("0x{x}", .{ev.a[i]}), + } + } + try w.writeAll(")"); +} + +/// A `syscall_exit` event's result: " = 3", " = 0x7f0000001000", " = -2 ENOENT". +pub fn formatExit(w: *std.Io.Writer, ev: *const Event) !void { + const ret: i64 = @bitCast(ev.a[0]); + if (ret < 0 and ret > -4096) { + try w.print(" = {d}", .{ret}); + if (std.enums.fromInt(linux.E, -ret)) |e| try w.print(" E{t}", .{e}); + } else if (ret < 0 or ret > 0xffffff) try w.print(" = 0x{x}", .{ev.a[0]}) else try w.print(" = {d}", .{ret}); +} + +/// A sink that prints each syscall a line and passes every event on. +pub const Printer = struct { + w: *std.Io.Writer, + next: ?event.Sink = null, + /// A call is printed and its result is not. + open: bool = false, + + pub fn sink(p: *Printer) event.Sink { + return .{ .ctx = p, .emitFn = emit }; + } + + fn emit(ctx: *anyopaque, ev: *const Event, payload: []const u8) anyerror!void { + const p: *Printer = @ptrCast(@alignCast(ctx)); + switch (ev.kind) { + .syscall_enter => { + // Another thread's call, or one that never returned (exit). + if (p.open) try p.w.writeAll(" ...\n"); + try formatEnter(p.w, ev, payload); + p.open = true; + }, + .syscall_exit, .exit => if (p.open) { + if (ev.kind == .exit) try p.w.writeAll(" = ?") else try formatExit(p.w, ev); + try p.w.writeAll("\n"); + try p.w.flush(); + p.open = false; + }, + else => {}, + } + if (p.next) |next| try next.emit(ev.*, payload); + } +}; + +test "a call prints the way strace prints it" { + var buf: [256]u8 = undefined; + var w: std.Io.Writer = .fixed(&buf); + var p: Printer = .{ .w = &w }; + const at_fdcwd: u64 = @as(u32, @bitCast(@as(i32, -100))); + try p.sink().emit(.{ .kind = .syscall_enter, .aux = @backingInt(linux.SYS.openat), .a = .{ at_fdcwd, 0x1000, 0x80000, 0, 0, 0 } }, "/etc/passwd"); + try p.sink().emit(.{ .kind = .syscall_exit, .aux = @backingInt(linux.SYS.openat), .a = .{ @bitCast(@as(i64, -2)), 0, 0, 0, 0, 0 } }, ""); + try p.sink().emit(.{ .kind = .syscall_enter, .aux = @backingInt(linux.SYS.write), .a = .{ 1, 0x2000, 3, 0, 0, 0 } }, "hi\n"); + try p.sink().emit(.{ .kind = .syscall_exit, .aux = @backingInt(linux.SYS.write), .a = .{ 3, 0, 0, 0, 0, 0 } }, ""); + try std.testing.expectEqualStrings( + \\openat(-100, "/etc/passwd", 0x80000, 0x0) = -2 ENOENT + \\write(1, "hi\n", 3) = 3 + \\ + , w.buffered()); + try std.testing.expectEqualStrings("exit_group", name(231).?); + try std.testing.expect(name(100_000) == null); +} -- cgit v1.3