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>

3 files changed, 131 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,
diff --git a/integrationtests/timer_test.go b/integrationtests/timer_test.go
new file mode 100644
index 0000000..7d9b295
--- /dev/null
+++ b/integrationtests/timer_test.go
@@ -0,0 +1,43 @@
+package integrationtests
+
+import "testing"
+
+// posixTimerTraceArgs restricts tracing to the POSIX timer-family syscalls so
+// the test output is dominated by the lifecycle calls the workload issues.
+// Note: timerfd_create is intentionally NOT in this list — it belongs to the
+// IPC/eventfd family and returns an fd, whereas timer_create returns a timer_t
+// through an output pointer (a null_event in the tracer).
+var posixTimerTraceArgs = []string{
+	"-trace-syscalls",
+	"timer_create,timer_settime,timer_gettime,timer_getoverrun,timer_delete,timerfd_create",
+}
+
+// TestPosixTimerLifecycle verifies the POSIX per-process timer family is traced
+// end-to-end. The workload runs timer_create -> timer_settime -> timer_gettime
+// -> timer_getoverrun -> timer_delete; each must appear as an enter event.
+func TestPosixTimerLifecycle(t *testing.T) {
+	h := newTestHarness(t)
+	result, pid, err := h.RunWithIorArgs("posix-timer-lifecycle", defaultDuration, posixTimerTraceArgs)
+	if err != nil {
+		t.Fatalf("run scenario posix-timer-lifecycle: %v", err)
+	}
+
+	AssertNoUnexpectedPID(t, result, pid)
+	AssertNoUnexpectedComm(t, result, "ioworkload")
+	AssertEventsPresent(t, result, []ExpectedEvent{
+		{Tracepoint: "enter_timer_create", Comm: "ioworkload", MinCount: 1},
+		{Tracepoint: "enter_timer_settime", Comm: "ioworkload", MinCount: 1},
+		{Tracepoint: "enter_timer_gettime", Comm: "ioworkload", MinCount: 1},
+		{Tracepoint: "enter_timer_getoverrun", Comm: "ioworkload", MinCount: 1},
+		{Tracepoint: "enter_timer_delete", Comm: "ioworkload", MinCount: 1},
+	})
+
+	// timer_create is a null_event: it must NOT capture an fd-style path the way
+	// the fd-returning siblings do. In particular it must not be confused with
+	// timerfd_create, whose records carry a "timerfd:" descriptor path. Guard
+	// against that regression: no timer_create record should have a timerfd path.
+	if got := totalTracepointPathCount(result, "enter_timer_create", "timerfd:"); got != 0 {
+		t.Fatalf("enter_timer_create records with a timerfd: descriptor path = %d, want 0; "+
+			"timer_create returns a timer_t, not an fd, and must not be classified like timerfd_create", got)
+	}
+}