1PTRACE(2) Linux Programmer's Manual PTRACE(2)
2
6 ptrace - process trace
7
9 #include <sys/ptrace.h>
10 long ptrace(enum __ptrace_request request, pid_t pid,
12 void *addr, void *data);
13
15 The ptrace() system call provides a means by which one process (the
16 "tracer") may observe and control the execution of another process (the
17 "tracee"), and examine and change the tracee's memory and registers.
18 It is primarily used to implement breakpoint debugging and system call
19 tracing.
20 A tracee first needs to be attached to the tracer. Attachment and sub‐
22 sequent commands are per thread: in a multithreaded process, every
23 thread can be individually attached to a (potentially different)
24 tracer, or left not attached and thus not debugged. Therefore,
25 "tracee" always means "(one) thread", never "a (possibly multithreaded)
26 process". Ptrace commands are always sent to a specific tracee using a
27 call of the form
28 ptrace(PTRACE_foo, pid, ...)
30 where pid is the thread ID of the corresponding Linux thread.
32 (Note that in this page, a "multithreaded process" means a thread group
34 consisting of threads created using the clone(2) CLONE_THREAD flag.)
35 A process can initiate a trace by calling fork(2) and having the
37 resulting child do a PTRACE_TRACEME, followed (typically) by an
38 execve(2). Alternatively, one process may commence tracing another
39 process using PTRACE_ATTACH or PTRACE_SEIZE.
40 While being traced, the tracee will stop each time a signal is deliv‐
42 ered, even if the signal is being ignored. (An exception is SIGKILL,
43 which has its usual effect.) The tracer will be notified at its next
44 call to waitpid(2) (or one of the related "wait" system calls); that
45 call will return a status value containing information that indicates
46 the cause of the stop in the tracee. While the tracee is stopped, the
47 tracer can use various ptrace requests to inspect and modify the
48 tracee. The tracer then causes the tracee to continue, optionally
49 ignoring the delivered signal (or even delivering a different signal
50 instead).
51 If the PTRACE_O_TRACEEXEC option is not in effect, all successful calls
53 to execve(2) by the traced process will cause it to be sent a SIGTRAP
54 signal, giving the parent a chance to gain control before the new pro‐
55 gram begins execution.
56 When the tracer is finished tracing, it can cause the tracee to con‐
58 tinue executing in a normal, untraced mode via PTRACE_DETACH.
59 The value of request determines the action to be performed:
61 PTRACE_TRACEME
63 Indicate that this process is to be traced by its parent. A
64 process probably shouldn't make this request if its parent isn't
65 expecting to trace it. (pid, addr, and data are ignored.)
66 The PTRACE_TRACEME request is used only by the tracee; the
68 remaining requests are used only by the tracer. In the follow‐
69 ing requests, pid specifies the thread ID of the tracee to be
70 acted on. For requests other than PTRACE_ATTACH, PTRACE_SEIZE,
71 PTRACE_INTERRUPT, and PTRACE_KILL, the tracee must be stopped.
72 PTRACE_PEEKTEXT, PTRACE_PEEKDATA
74 Read a word at the address addr in the tracee's memory, return‐
75 ing the word as the result of the ptrace() call. Linux does not
76 have separate text and data address spaces, so these two
77 requests are currently equivalent. (data is ignored; but see
78 NOTES.)
79 PTRACE_PEEKUSER
81 Read a word at offset addr in the tracee's USER area, which
82 holds the registers and other information about the process (see
83 <sys/user.h>). The word is returned as the result of the
84 ptrace() call. Typically, the offset must be word-aligned,
85 though this might vary by architecture. See NOTES. (data is
86 ignored; but see NOTES.)
87 PTRACE_POKETEXT, PTRACE_POKEDATA
89 Copy the word data to the address addr in the tracee's memory.
90 As for PTRACE_PEEKTEXT and PTRACE_PEEKDATA, these two requests
91 are currently equivalent.
92 PTRACE_POKEUSER
94 Copy the word data to offset addr in the tracee's USER area. As
95 for PTRACE_PEEKUSER, the offset must typically be word-aligned.
96 In order to maintain the integrity of the kernel, some modifica‐
97 tions to the USER area are disallowed.
98 PTRACE_GETREGS, PTRACE_GETFPREGS
100 Copy the tracee's general-purpose or floating-point registers,
101 respectively, to the address data in the tracer. See
102 <sys/user.h> for information on the format of this data. (addr
103 is ignored.) Note that SPARC systems have the meaning of data
104 and addr reversed; that is, data is ignored and the registers
105 are copied to the address addr. PTRACE_GETREGS and PTRACE_GETF‐
106 PREGS are not present on all architectures.
107 PTRACE_GETREGSET (since Linux 2.6.34)
109 Read the tracee's registers. addr specifies, in an architec‐
110 ture-dependent way, the type of registers to be read. NT_PRSTA‐
111 TUS (with numerical value 1) usually results in reading of gen‐
112 eral-purpose registers. If the CPU has, for example, floating-
113 point and/or vector registers, they can be retrieved by setting
114 addr to the corresponding NT_foo constant. data points to a