From ce7c0abf14e7ab056d5479adc3f05df9976e94e4 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 11:44:48 -0300 Subject: agent: the in-process backend, and ztrace run's options for it libztrace-agent.so (preloaded) and libztrace-agent.a (linked in), one source: map and thread_start at startup; alloc/free from the interposed allocator; syscall_enter/exit through Syscall User Dispatch; call/ret from int3 hooks; mem_write from watched regions diffed in-process; the target-side API (include/ztrace.h, and the ztrace-agent module for Zig). ztrace run turns each on (--alloc --syscalls --hook --watch), chooses the moments (--cut), and stops the target at event kinds without ptrace (--stop-at, --read, -i). test-agent records real targets and checks the recordings. Co-Authored-By: Claude Fable 5.2 --- include/ztrace.h | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 include/ztrace.h (limited to 'include') diff --git a/include/ztrace.h b/include/ztrace.h new file mode 100644 index 0000000..d507809 --- /dev/null +++ b/include/ztrace.h @@ -0,0 +1,37 @@ +/* ztrace: what a traced program can say about itself. + * + * Link libztrace-agent.a (or libztrace-agent.so) and run the program under + * `ztrace run`. Run without a tracer, these do nothing. + * + * A statically linked agent sees the allocator and thread creation when the + * program is linked with: + * -Wl,--wrap=malloc,--wrap=calloc,--wrap=realloc,--wrap=free + * -Wl,--wrap=posix_memalign,--wrap=aligned_alloc,--wrap=memalign + * -Wl,--wrap=pthread_create,--wrap=fork + */ +#ifndef ZTRACE_H +#define ZTRACE_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* A point in the run worth a moment of the recording: a `mark` event. */ +void ztrace_mark(const char *label, uint64_t value); + +/* Names `len` bytes at `ptr` (a `variable` event), records them, and keeps + * recording what changes in them: only the bytes that changed, at each event + * that ends a moment. The memory must stay mapped. */ +void ztrace_watch(const void *ptr, size_t len, const char *name); + +/* Records `len` bytes at `ptr` as they are now, once. */ +void ztrace_snapshot(const void *ptr, size_t len); + +#ifdef __cplusplus +} +#endif + +#endif -- cgit v1.3