1ptrace(2) System Calls Manual ptrace(2)
2
6 ptrace - process trace
7
9 Standard C library (libc, -lc)
10
12 #include <sys/ptrace.h>
13 long ptrace(enum __ptrace_request request, pid_t pid,
15 void *addr, void *data);
16
18 The ptrace() system call provides a means by which one process (the
19 "tracer") may observe and control the execution of another process (the
20 "tracee"), and examine and change the tracee's memory and registers.
21 It is primarily used to implement breakpoint debugging and system call
22 tracing.
23 A tracee first needs to be attached to the tracer. Attachment and sub‐
25 sequent commands are per thread: in a multithreaded process, every
26 thread can be individually attached to a (potentially different)
27 tracer, or left not attached and thus not debugged. Therefore,
28 "tracee" always means "(one) thread", never "a (possibly multithreaded)
29 process". Ptrace commands are always sent to a specific tracee using a
30 call of the form
31 ptrace(PTRACE_foo, pid, ...)
33 where pid is the thread ID of the corresponding Linux thread.
35 (Note that in this page, a "multithreaded process" means a thread group
37 consisting of threads created using the clone(2) CLONE_THREAD flag.)
38 A process can initiate a trace by calling fork(2) and having the re‐
40 sulting child do a PTRACE_TRACEME, followed (typically) by an ex‐
41 ecve(2). Alternatively, one process may commence tracing another
42 process using PTRACE_ATTACH or PTRACE_SEIZE.
43 While being traced, the tracee will stop each time a signal is deliv‐
45 ered, even if the signal is being ignored. (An exception is SIGKILL,
46 which has its usual effect.) The tracer will be notified at its next
47 call to waitpid(2) (or one of the related "wait" system calls); that
48 call will return a status value containing information that indicates
49 the cause of the stop in the tracee. While the tracee is stopped, the
50 tracer can use various ptrace requests to inspect and modify the
51 tracee. The tracer then causes the tracee to continue, optionally ig‐
52 noring the delivered signal (or even delivering a different signal in‐
53 stead).
54 If the PTRACE_O_TRACEEXEC option is not in effect, all successful calls
56 to execve(2) by the traced process will cause it to be sent a SIGTRAP
57 signal, giving the parent a chance to gain control before the new pro‐