ptrace and Debugging Interfaces

Coverage: ptrace(PTRACE_ATTACH/PTRACE_SYSCALL/PTRACE_PEEKDATA/PTRACE_GETREGS) → strace/gdb implementation principles → /proc/pid/mem → seccomp user notify Applicable to: Linux user space, x86-64/ARM64

Overview

ptrace is the oldest debugging interface in Unix—it allows a tracer process to fully control a tracee process. gdb (breakpoints, single-stepping, register read/write) and strace (system call tracing) are both built on ptrace. In recent years, more efficient alternatives have emerged (/proc/pid/mem, seccomp user notify), but ptrace remains the most universal.

Core ptrace Operations

#include <sys/ptrace.h>

// Attach (self or others):
ptrace(PTRACE_TRACEME, 0, 0, 0);            // tracee declares "can be traced"
// or
ptrace(PTRACE_ATTACH, target_pid, 0, 0);    // tracer attaches to tracee
ptrace(PTRACE_SEIZE, target_pid, 0, opts);  // attach but do not stop (SEIZE, 3.4+)

// Control:
ptrace(PTRACE_CONT, pid, 0, sig);           // continue execution (optional injected signal)
ptrace(PTRACE_SYSCALL, pid, 0, 0);          // stop at syscall entry + exit
ptrace(PTRACE_SINGLESTEP, pid, 0, 0);       // single-step one instruction

// Read/Write:
ptrace(PTRACE_PEEKDATA, pid, addr, 0);      // read tracee memory (word at a time)
ptrace(PTRACE_POKEDATA, pid, addr, data);   // write tracee memory
ptrace(PTRACE_GETREGS, pid, 0, &regs);      // read registers
ptrace(PTRACE_SETREGS, pid, 0, &regs);      // write registers

// Detach:
ptrace(PTRACE_DETACH, pid, 0, 0);

strace Principles

// Core logic of strace (simplified):

// 1. Fork child process
pid = fork();
if (pid == 0) {
    ptrace(PTRACE_TRACEME, 0, 0, 0);
    execve(argv[1], &argv[1], envp);
}

// 2. Parent process (tracer):
waitpid(pid, &status, 0);  // wait for first stop (SIGTRAP after execve)

while (1) {
    ptrace(PTRACE_SYSCALL, pid, 0, 0);   // tell kernel: stop on syscall
    waitpid(pid, &status, 0);             // wait for stop

    if (WIFEXITED(status)) break;

    // tracee stopped at syscall entry → read arguments
    ptrace(PTRACE_GETREGS, pid, 0, &regs);
    // x86: regs.orig_rax = syscall number, regs.rdi/rsi/rdx = args 0-2

    // Continue to syscall exit:
    ptrace(PTRACE_SYSCALL, pid, 0, 0);
    waitpid(pid, &status, 0);
    ptrace(PTRACE_GETREGS, pid, 0, &regs);
    // regs.rax = return value (possibly -errno)
}

Every syscall entry/exit goes through: tracer → PTRACE_SYSCALL → waitpid → GETREGS → PTRACE_SYSCALL → waitpid → GETREGS. This is the root cause of strace's high overhead—each traced system call requires 4 context switches (tracee→tracer→tracee→tracer).

gdb Principles

Breakpoints:
  gdb uses PTRACE_PEEKDATA to read the instruction at the breakpoint location → saves it
  Uses PTRACE_POKEDATA to replace that location with INT3 (0xCC)
  Execution reaches INT3 → SIGTRAP → tracer is notified (waitpid)
  Tracer restores original instruction → single-step or continue

Single-stepping:
  PTRACE_SINGLESTEP → CPU executes 1 instruction → SIGTRAP → tracer

Register read/write:
  PTRACE_GETREGS / PTRACE_SETREGS

Memory read/write:
  PTRACE_PEEKDATA / PTRACE_POKEDATA (slow, per-word)
  /proc/pid/mem: more efficient (pread/pwrite, arbitrary size)

/proc/pid/mem: An Alternative to ptrace

// No need for ptrace ATTACH → read/write tracee's virtual memory
// But ptrace ATTACH is required to write to non-rw regions (before 5.x)
// 5.x+: process_vm_readv/writev is more efficient (no need to open /proc/pid/mem)

int memfd = open("/proc/<pid>/mem", O_RDWR);
pread(memfd, buf, size, addr);  // read tracee address addr
pwrite(memfd, buf, size, addr); // write tracee address addr

seccomp user notify: "ptrace for the New Era"

// SECCOMP_RET_USER_NOTIF: seccomp filter notifies the supervisor process of syscalls
// Supervisor can check/modify/approve/reject → no need for ptrace (much lower overhead)

// Problems with ptrace:
//   All syscalls stop → tracer → tracee (even for syscalls not of interest)
// seccomp user notify:
//   Only intercepts syscalls matching the seccomp filter → others are unaffected
//   → ptrace overhead is O(all syscalls), seccomp is O(interested ones)

Debugger Limitations

1. A process can only have 1 tracer (multiple straces are not allowed)
2. Processes after PTRACE_TRACEME cannot setuid (security restriction)
3. Cannot trace init (PID 1)
4. Yama LSM: /proc/sys/kernel/yama/ptrace_scope restricts who can trace
   0: Anyone can trace anyone (permissive)
   1: Can only trace self or descendants (default)
   2: Can only trace descendants (admin override)
   3: Completely disable ptrace

References

• man: ptrace(2)
• Source code: kernel/ptrace.c, kernel/seccomp.c
• LWN: "Better ptrace", "Seccomp user-space notification"

Keywords: ptrace, PTRACE_ATTACH, PTRACE_SYSCALL, PTRACE_SINGLESTEP, PTRACE_PEEKDATA, strace, gdb, /proc/pid/mem, seccomp user notify, Yama