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 a parent process may
16 observe and control the execution of another process, and examine and
17 change its core image and registers. It is primarily used to implement
18 breakpoint debugging and system call tracing.
19 The parent can initiate a trace by calling fork(2) and having the
21 resulting child do a PTRACE_TRACEME, followed (typically) by an
22 exec(3). Alternatively, the parent may commence trace of an existing
23 process using PTRACE_ATTACH.
24 While being traced, the child will stop each time a signal is deliv‐
26 ered, even if the signal is being ignored. (The exception is SIGKILL,
27 which has its usual effect.) The parent will be notified at its next
28 wait(2) and may inspect and modify the child process while it is
29 stopped. The parent then causes the child to continue, optionally
30 ignoring the delivered signal (or even delivering a different signal
31 instead).
32 When the parent is finished tracing, it can terminate the child with
34 PTRACE_KILL or cause it to continue executing in a normal, untraced
35 mode via PTRACE_DETACH.
36 The value of request determines the action to be performed:
38 PTRACE_TRACEME
40 Indicates that this process is to be traced by its parent. Any
41 signal (except SIGKILL) delivered to this process will cause it
42 to stop and its parent to be notified via wait(2). Also, all
43 subsequent calls to execve(2) by this process will cause a SIG‐
44 TRAP to be sent to it, giving the parent a chance to gain con‐
45 trol before the new program begins execution. A process proba‐
46 bly shouldn't make this request if its parent isn't expecting to
47 trace it. (pid, addr, and data are ignored.)
48 The above request is used only by the child process; the rest are used
50 only by the parent. In the following requests, pid specifies the child
51 process to be acted on. For requests other than PTRACE_KILL, the child
52 process must be stopped.
53 PTRACE_PEEKTEXT, PTRACE_PEEKDATA
55 Reads a word at the location addr in the child's memory, return‐
56 ing the word as the result of the ptrace() call. Linux does not
57 have separate text and data address spaces, so the two requests
58 are currently equivalent. (The argument data is ignored.)
59 PTRACE_PEEKUSER
61 Reads a word at offset addr in the child's USER area, which
62 holds the registers and other information about the process (see
63 <sys/user.h>). The word is returned as the result of the
64 ptrace() call. Typically the offset must be word-aligned,
65 though this might vary by architecture. See NOTES. (data is
66 ignored.)
67 PTRACE_POKETEXT, PTRACE_POKEDATA
69 Copies the word data to location addr in the child's memory. As
70 above, the two requests are currently equivalent.
71 PTRACE_POKEUSER
73 Copies the word data to offset addr in the child's USER area.
74 As above, the offset must typically be word-aligned. In order
75 to maintain the integrity of the kernel, some modifications to
76 the USER area are disallowed.
77 PTRACE_GETREGS, PTRACE_GETFPREGS
79 Copies the child's general purpose or floating-point registers,
80 respectively, to location data in the parent. See <sys/user.h>
81 for information on the format of this data. (addr is ignored.)
82 PTRACE_GETSIGINFO (since Linux 2.3.99-pre6)
84 Retrieve information about the signal that caused the stop.
85 Copies a siginfo_t structure (see sigaction(2)) from the child
86 to location data in the parent. (addr is ignored.)
87 PTRACE_SETREGS, PTRACE_SETFPREGS
89 Copies the child's general purpose or floating-point registers,
90 respectively, from location data in the parent. As for
91 PTRACE_POKEUSER, some general purpose register modifications may
92 be disallowed. (addr is ignored.)
93 PTRACE_SETSIGINFO (since Linux 2.3.99-pre6)
95 Set signal information. Copies a siginfo_t structure from loca‐
96 tion data in the parent to the child. This will only affect
97 signals that would normally be delivered to the child and were
98 caught by the tracer. It may be difficult to tell these normal
99 signals from synthetic signals generated by ptrace() itself.
100 (addr is ignored.)
101 PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats)
103 Sets ptrace options from data in the parent. (addr is ignored.)
104 data is interpreted as a bit mask of options, which are speci‐
105 fied by the following flags:
106 PTRACE_O_TRACESYSGOOD (since Linux 2.4.6)
108 When delivering syscall traps, set bit 7 in the signal
109 number (i.e., deliver (SIGTRAP | 0x80) This makes it easy
110 for the tracer to tell the difference between normal
111 traps and those caused by a syscall. (PTRACE_O_TRACESYS‐
112 GOOD may not work on all architectures.)
113 PTRACE_O_TRACEFORK (since Linux 2.5.46)
115 Stop the child at the next fork(2) call with SIGTRAP |
116 PTRACE_EVENT_FORK << 8 and automatically start tracing
117 the newly forked process, which will start with a
118 SIGSTOP. The PID for the new process can be retrieved
119 with PTRACE_GETEVENTMSG.
120 PTRACE_O_TRACEVFORK (since Linux 2.5.46)
122 Stop the child at the next vfork(2) call with SIGTRAP |
123 PTRACE_EVENT_VFORK << 8 and automatically start tracing
124 the newly vforked process, which will start with a
125 SIGSTOP. The PID for the new process can be retrieved
126 with PTRACE_GETEVENTMSG.
127 PTRACE_O_TRACECLONE (since Linux 2.5.46)
129 Stop the child at the next clone(2) call with SIGTRAP |
130 PTRACE_EVENT_CLONE << 8 and automatically start tracing
131 the newly cloned process, which will start with a
132 SIGSTOP. The PID for the new process can be retrieved
133 with PTRACE_GETEVENTMSG. This option may not catch
134 clone(2) calls in all cases. If the child calls clone(2)
135 with the CLONE_VFORK flag, PTRACE_EVENT_VFORK will be
136 delivered instead if PTRACE_O_TRACEVFORK is set; other‐
137 wise if the child calls clone(2) with the exit signal set
138 to SIGCHLD, PTRACE_EVENT_FORK will be delivered if
139 PTRACE_O_TRACEFORK is set.
140 PTRACE_O_TRACEEXEC (since Linux 2.5.46)
142 Stop the child at the next execve(2) call with SIGTRAP |
143 PTRACE_EVENT_EXEC << 8.
144 PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60)
146 Stop the child at the completion of the next vfork(2)
147 call with SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8.
148 PTRACE_O_TRACEEXIT (since Linux 2.5.60)
150 Stop the child at exit with SIGTRAP |
151 PTRACE_EVENT_EXIT << 8. The child's exit status can be
152 retrieved with PTRACE_GETEVENTMSG. This stop will be
153 done early during process exit when registers are still
154 available, allowing the tracer to see where the exit
155 occurred, whereas the normal exit notification is done
156 after the process is finished exiting. Even though con‐
157 text is available, the tracer cannot prevent the exit
158 from happening at this point.
159 PTRACE_GETEVENTMSG (since Linux 2.5.46)
161 Retrieve a message (as an unsigned long) about the ptrace event
162 that just happened, placing it in the location data in the par‐
163 ent. For PTRACE_EVENT_EXIT this is the child's exit status.
164 For PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK and PTRACE_EVENT_CLONE
165 this is the PID of the new process. Since Linux 2.6.18, the PID
166 of the new process is also available for
167 PTRACE_EVENT_VFORK_DONE. (addr is ignored.)
168 PTRACE_CONT
170 Restarts the stopped child process. If data is nonzero and not
171 SIGSTOP, it is interpreted as a signal to be delivered to the
172 child; otherwise, no signal is delivered. Thus, for example,
173 the parent can control whether a signal sent to the child is
174 delivered or not. (addr is ignored.)
175 PTRACE_SYSCALL, PTRACE_SINGLESTEP
177 Restarts the stopped child as for PTRACE_CONT, but arranges for
178 the child to be stopped at the next entry to or exit from a sys‐
179 tem call, or after execution of a single instruction, respec‐
180 tively. (The child will also, as usual, be stopped upon receipt
181 of a signal.) From the parent's perspective, the child will
182 appear to have been stopped by receipt of a SIGTRAP. So, for
183 PTRACE_SYSCALL, for example, the idea is to inspect the argu‐
184 ments to the system call at the first stop, then do another
185 PTRACE_SYSCALL and inspect the return value of the system call
186 at the second stop. The data argument is treated as for
187 PTRACE_CONT. (addr is ignored.)
188 PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14)
190 For PTRACE_SYSEMU, continue and stop on entry to the next
191 syscall, which will not be executed. For PTRACE_SYSEMU_SIN‐
192 GLESTEP, do the same but also singlestep if not a syscall. This
193 call is used by programs like User Mode Linux that want to emu‐
194 late all the child's system calls. The data argument is treated
195 as for PTRACE_CONT. (addr is ignored; not supported on all
196 architectures.)
197 PTRACE_KILL
199 Sends the child a SIGKILL to terminate it. (addr and data are
200 ignored.)
201 PTRACE_ATTACH
203 Attaches to the process specified in pid, making it a traced
204 "child" of the calling process; the behavior of the child is as
205 if it had done a PTRACE_TRACEME. The calling process actually
206 becomes the parent of the child process for most purposes (e.g.,
207 it will receive notification of child events and appears in
208 ps(1) output as the child's parent), but a getppid(2) by the
209 child will still return the PID of the original parent. The
210 child is sent a SIGSTOP, but will not necessarily have stopped
211 by the completion of this call; use wait(2) to wait for the
212 child to stop. (addr and data are ignored.)
213 PTRACE_DETACH
215 Restarts the stopped child as for PTRACE_CONT, but first
216 detaches from the process, undoing the reparenting effect of
217 PTRACE_ATTACH, and the effects of PTRACE_TRACEME. Although per‐
218 haps not intended, under Linux a traced child can be detached in
219 this way regardless of which method was used to initiate trac‐
220 ing. (addr is ignored.)
221
223 On success, PTRACE_PEEK* requests return the requested data, while
224 other requests return zero. On error, all requests return -1, and
225 errno is set appropriately. Since the value returned by a successful
226 PTRACE_PEEK* request may be -1, the caller must check errno after such
227 requests to determine whether or not an error occurred.
228
230 EBUSY (i386 only) There was an error with allocating or freeing a
231 debug register.
232 EFAULT There was an attempt to read from or write to an invalid area in
234 the parent's or child's memory, probably because the area wasn't
235 mapped or accessible. Unfortunately, under Linux, different
236 variations of this fault will return EIO or EFAULT more or less
237 arbitrarily.
238 EINVAL An attempt was made to set an invalid option.
240 EIO request is invalid, or an attempt was made to read from or write
242 to an invalid area in the parent's or child's memory, or there
243 was a word-alignment violation, or an invalid signal was speci‐
244 fied during a restart request.
245 EPERM The specified process cannot be traced. This could be because
247 the parent has insufficient privileges (the required capability
248 is CAP_SYS_PTRACE); unprivileged processes cannot trace pro‐
249 cesses that they cannot send signals to or those running set-
250 user-ID/set-group-ID programs, for obvious reasons. Alterna‐
251 tively, the process may already be being traced, or be init(8)
252 (PID 1).
253 ESRCH The specified process does not exist, or is not currently being
255 traced by the caller, or is not stopped (for requests that
256 require that).
257
259 SVr4, 4.3BSD.
260
262 Although arguments to ptrace() are interpreted according to the proto‐
263 type given, glibc currently declares ptrace() as a variadic function
264 with only the request argument fixed. This means that unneeded trail‐
265 ing arguments may be omitted, though doing so makes use of undocumented
266 gcc(1) behavior.
267 init(8), the process with PID 1, may not be traced.
269 The layout of the contents of memory and the USER area are quite OS-
271 and architecture-specific. The offset supplied, and the data returned,
272 might not entirely match with the definition of struct user.
273 The size of a "word" is determined by the OS variant (e.g., for 32-bit
275 Linux it is 32 bits, etc.).
276 Tracing causes a few subtle differences in the semantics of traced pro‐
278 cesses. For example, if a process is attached to with PTRACE_ATTACH,
279 its original parent can no longer receive notification via wait(2) when
280 it stops, and there is no way for the new parent to effectively simu‐
281 late this notification.
282 When the parent receives an event with PTRACE_EVENT_* set, the child is
284 not in the normal signal delivery path. This means the parent cannot
285 do ptrace(PTRACE_CONT) with a signal or ptrace(PTRACE_KILL). kill(2)
286 with a SIGKILL signal can be used instead to kill the child process
287 after receiving one of these messages.
288 This page documents the way the ptrace() call works currently in Linux.
290 Its behavior differs noticeably on other flavors of Unix. In any case,
291 use of ptrace() is highly OS- and architecture-specific.
292 The SunOS man page describes ptrace() as "unique and arcane", which it
294 is. The proc-based debugging interface present in Solaris 2 implements
295 a superset of ptrace() functionality in a more powerful and uniform
296 way.
297
299 On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared with a
300 different value than the one for 2.4. This leads to applications com‐
301 piled with such headers failing when run on 2.4 kernels. This can be
302 worked around by redefining PTRACE_SETOPTIONS to PTRACE_OLDSETOPTIONS,
303 if that is defined.
304
306 gdb(1), strace(1), execve(2), fork(2), signal(2), wait(2), exec(3),
307 capabilities(7)
308
310 This page is part of release 3.25 of the Linux man-pages project. A
311 description of the project, and information about reporting bugs, can
312 be found at http://www.kernel.org/doc/man-pages/.
313Linux 2009-03-30 PTRACE(2)