summaryrefslogtreecommitdiff
path: root/include
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:44:48 -0300
committerGabriel Schneider <[email protected]>2026-11-10 12:09:34 -0300
commitce7c0abf14e7ab056d5479adc3f05df9976e94e4 (patch)
tree8931de9a55b3d7c2ec2d52d3b3817c6f7eb5db5a /include
parente7aa7801c10ed34194b7fe3f5ca8722a72404e65 (diff)
downloadcomputeranim-ce7c0abf14e7ab056d5479adc3f05df9976e94e4.tar.gz
computeranim-ce7c0abf14e7ab056d5479adc3f05df9976e94e4.zip
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 <[email protected]>
Diffstat (limited to 'include')
-rw-r--r--include/ztrace.h37
1 files changed, 37 insertions, 0 deletions
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 <stddef.h>
+#include <stdint.h>
+
+#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