test(timer): add POSIX timer family end-to-end integration coverage

The POSIX per-process timer family (timer_create, timer_settime,
timer_gettime, timer_getoverrun, timer_delete) had no end-to-end
integration coverage; only the unrelated fd-returning sibling
timerfd_create was exercised. Add a posix-timer-lifecycle workload
scenario and TestPosixTimerLifecycle to validate these are traced as
null_events, and guard against timer_create being misclassified like
timerfd_create (timer_create returns a timer_t via an output pointer,
not an fd, so its records must carry no 'timerfd:' descriptor path).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2 files changed, 88 insertions, 0 deletions

diff --git a/cmd/ioworkload/scenario_timer.go b/cmd/ioworkload/scenario_timer.go
new file mode 100644
index 0000000..0bf628d
--- /dev/null
+++ b/cmd/ioworkload/scenario_timer.go
@@ -0,0 +1,87 @@
+package main
+
+import (
+	"fmt"
+	"syscall"
+	"unsafe"
+
+	"golang.org/x/sys/unix"
+)
+
+// itimerspec mirrors struct itimerspec from <time.h> (it_interval, it_value).
+// Used as the argument to timer_settime / timer_gettime.
+type itimerspec struct {
+	Interval unix.Timespec
+	Value    unix.Timespec
+}
+
+// posixTimerLifecycle exercises the full POSIX per-process timer family so the
+// tracer's null_event handling is covered end-to-end:
+//
+//	timer_create -> timer_settime -> timer_gettime -> timer_getoverrun -> timer_delete
+//
+// These are deliberately distinct from timerfd_create: timer_create returns a
+// timer_t through an OUTPUT pointer (args[2]), NOT a file descriptor, so the
+// tracer must emit a null_event for it and must never treat any argument or the
+// return value as an fd (contrast with timerfd_create, which is an fd-returning
+// eventfd-family syscall). See man 2 timer_create.
+func posixTimerLifecycle() error {
+	// timer_t (__kernel_timer_t) is an int in the Linux UAPI, not an fd.
+	var timerID int32
+
+	// timer_create(CLOCK_MONOTONIC, NULL, &timerID): a NULL sigevent requests
+	// the default notification (SIGALRM via signal), and timerID is the output
+	// timer_t — not an fd.
+	if _, _, errno := syscall.RawSyscall(
+		unix.SYS_TIMER_CREATE,
+		uintptr(unix.CLOCK_MONOTONIC),
+		0, // sevp == NULL
+		uintptr(unsafe.Pointer(&timerID)),
+	); errno != 0 {
+		return fmt.Errorf("timer_create: %w", errno)
+	}
+
+	// Arm the timer with a far-future one-shot expiry so it never actually
+	// fires during the test; we only care about the syscalls being traced.
+	newValue := itimerspec{
+		Value: unix.Timespec{Sec: 3600, Nsec: 0},
+	}
+	if _, _, errno := syscall.RawSyscall6(
+		unix.SYS_TIMER_SETTIME,
+		uintptr(timerID),
+		0, // flags (relative)
+		uintptr(unsafe.Pointer(&newValue)),
+		0, // old_value == NULL
+		0, 0,
+	); errno != 0 {
+		return fmt.Errorf("timer_settime: %w", errno)
+	}
+
+	var curValue itimerspec
+	if _, _, errno := syscall.RawSyscall(
+		unix.SYS_TIMER_GETTIME,
+		uintptr(timerID),
+		uintptr(unsafe.Pointer(&curValue)),
+		0,
+	); errno != 0 {
+		return fmt.Errorf("timer_gettime: %w", errno)
+	}
+
+	if _, _, errno := syscall.RawSyscall(
+		unix.SYS_TIMER_GETOVERRUN,
+		uintptr(timerID),
+		0, 0,
+	); errno != 0 {
+		return fmt.Errorf("timer_getoverrun: %w", errno)
+	}
+
+	if _, _, errno := syscall.RawSyscall(
+		unix.SYS_TIMER_DELETE,
+		uintptr(timerID),
+		0, 0,
+	); errno != 0 {
+		return fmt.Errorf("timer_delete: %w", errno)
+	}
+
+	return nil
+}
diff --git a/cmd/ioworkload/scenarios.go b/cmd/ioworkload/scenarios.go
index 08ac7a3..3feb76c 100644
--- a/cmd/ioworkload/scenarios.go
+++ b/cmd/ioworkload/scenarios.go
@@ -42,6 +42,7 @@ var scenarios = map[string]func() error{
 	"mountfs-management":            mountfsManagement,
 	"polling-epoll":                 pollingEpoll,
 	"sleep-syscalls":                sleepSyscalls,
+	"posix-timer-lifecycle":         posixTimerLifecycle,
 	"process-exec-lifecycle":        processExecLifecycle,
 	"family-mixed":                  familyMixed,
 	"close-basic":                   closeBasic,