summaryrefslogtreecommitdiff
path: root/src/trace/syscalls.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:43:24 -0300
committerGabriel Schneider <[email protected]>2026-11-10 11:58:53 -0300
commit3fdb67c479dcc1ad0f1e51832bc086622692249c (patch)
treedcc2e947644cb6d9a8bb0a19a29153256f4bc951 /src/trace/syscalls.zig
parentf15f4670991110829dcf123625c049224eba9838 (diff)
downloadcomputeranim-3fdb67c479dcc1ad0f1e51832bc086622692249c.tar.gz
computeranim-3fdb67c479dcc1ad0f1e51832bc086622692249c.zip
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 <[email protected]>
Diffstat (limited to 'src/trace/syscalls.zig')
-rw-r--r--src/trace/syscalls.zig141
1 files changed, 141 insertions, 0 deletions
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);
+}