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(). Also, all
43 subsequent calls to exec() by this process will cause a SIGTRAP
44 to be sent to it, giving the parent a chance to gain control
45 before the new program begins execution. A process probably
46 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_PEEKUSR
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 <linux/user.h> and <sys/user.h>). The word is returned as the
64 result of the ptrace() call. Typically the offset must be word-
65 aligned, though this might vary by architecture. (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_POKEUSR
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
81 <linux/user.h> for information on the format of this data.
82 (addr is ignored.)
83 PTRACE_GETSIGINFO (since Linux 2.3.99-pre6)
85 Retrieve information about the signal that caused the stop.
86 Copies a siginfo_t structure (see sigaction(2)) from the child
87 to location data in the parent. (addr is ignored.)
88 PTRACE_SETREGS, PTRACE_SETFPREGS
90 Copies the child's general purpose or floating-point registers,
91 respectively, from location data in the parent. As for
92 PTRACE_POKEUSER, some general purpose register modifications may
93 be disallowed. (addr is ignored.)
94 PTRACE_SETSIGINFO (since Linux 2.3.99-pre6)
96 Set signal information. Copies a siginfo_t structure from loca‐
97 tion data in the parent to the child. This will only affect
98 signals that would normally be delivered to the child and were
99 caught by the tracer. It may be difficult to tell these normal
100 signals from synthetic signals generated by ptrace() itself.
101 (addr is ignored.)
102 PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats)
104 Sets ptrace options from data in the parent. (addr is ignored.)
105 data is interpreted as a bitmask of options, which are specified
106 by the following flags:
107 PTRACE_O_TRACESYSGOOD (since Linux 2.4.6)
109 When delivering syscall traps, set bit 7 in the signal
110 number (i.e., deliver (SIGTRAP | 0x80) This makes it easy
111 for the tracer to tell the difference between normal
112 traps and those caused by a syscall. (PTRACE_O_TRACESYS‐
113 GOOD may not work on all architectures.)
114 PTRACE_O_TRACEFORK (since Linux 2.5.46)
116 Stop the child at the next fork() call with SIGTRAP |
117 PTRACE_EVENT_FORK << 8 and automatically start tracing
118 the newly forked process, which will start with a
119 SIGSTOP. The PID for the new process can be retrieved
120 with PTRACE_GETEVENTMSG.
121 PTRACE_O_TRACEVFORK (since Linux 2.5.46)
123 Stop the child at the next vfork() call with SIGTRAP |
124 PTRACE_EVENT_VFORK << 8 and automatically start tracing
125 the newly vforked process, which will start with a
126 SIGSTOP. The PID for the new process can be retrieved
127 with PTRACE_GETEVENTMSG.
128 PTRACE_O_TRACECLONE (since Linux 2.5.46)
130 Stop the child at the next clone() call with SIGTRAP |
131 PTRACE_EVENT_CLONE << 8 and automatically start tracing
132 the newly cloned process, which will start with a
133 SIGSTOP. The PID for the new process can be retrieved
134 with PTRACE_GETEVENTMSG. This option may not catch
135 clone() calls in all cases. If the child calls clone()
136 with the CLONE_VFORK flag, PTRACE_EVENT_VFORK will be
137 delivered instead if PTRACE_O_TRACEVFORK is set; other‐
138 wise if the child calls clone() with the exit signal set
139 to SIGCHLD, PTRACE_EVENT_FORK will be delivered if
140 PTRACE_O_TRACEFORK is set.
141 PTRACE_O_TRACEEXEC (since Linux 2.5.46)
143 Stop the child at the next exec() call with SIGTRAP |
144 PTRACE_EVENT_EXEC << 8.
145 PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60)
147 Stop the child at the completion of the next vfork() call
148 with SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8.
149 PTRACE_O_TRACEEXIT (since Linux 2.5.60)
151 Stop the child at exit with SIGTRAP | PTRACE_EVENT_EXIT
152 << 8. The child's exit status can be retrieved with
153 PTRACE_GETEVENTMSG. This stop will be done early during
154 process exit when registers are still available, allowing
155 the tracer to see where the exit occurred, whereas the
156 normal exit notification is done after the process is
157 finished exiting. Even though context is available, the
158 tracer cannot prevent the exit from happening at this
159 point.
160 PTRACE_GETEVENTMSG (since Linux 2.5.46)
162 Retrieve a message (as an unsigned long) about the ptrace event
163 that just happened, placing it in the location data in the par‐
164 ent. For PTRACE_EVENT_EXIT this is the child's exit status.
165 For PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK and PTRACE_EVENT_CLONE
166 this is the PID of the new process. Since Linux 2.6.18, the PID
167 of the new process is also available for
168 PTRACE_EVENT_VFORK_DONE. (addr is ignored.)
169 PTRACE_CONT
171 Restarts the stopped child process. If data is non-zero and not
172 SIGSTOP, it is interpreted as a signal to be delivered to the
173 child; otherwise, no signal is delivered. Thus, for example,
174 the parent can control whether a signal sent to the child is
175 delivered or not. (addr is ignored.)
176 PTRACE_SYSCALL, PTRACE_SINGLESTEP
178 Restarts the stopped child as for PTRACE_CONT, but arranges for
179 the child to be stopped at the next entry to or exit from a sys‐
180 tem call, or after execution of a single instruction, respec‐
181 tively. (The child will also, as usual, be stopped upon receipt
182 of a signal.) From the parent's perspective, the child will
183 appear to have been stopped by receipt of a SIGTRAP. So, for
184 PTRACE_SYSCALL, for example, the idea is to inspect the argu‐
185 ments to the system call at the first stop, then do another
186 PTRACE_SYSCALL and inspect the return value of the system call
187 at the second stop. (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. (addr and data are ignored;
195 not supported on all architectures.)
196 PTRACE_KILL
198 Sends the child a SIGKILL to terminate it. (addr and data are
199 ignored.)
200 PTRACE_ATTACH
202 Attaches to the process specified in pid, making it a traced
203 "child" of the current process; the behavior of the child is as
204 if it had done a PTRACE_TRACEME. The current process actually
205 becomes the parent of the child process for most purposes (e.g.,
206 it will receive notification of child events and appears in
207 ps(1) output as the child's parent), but a getppid(2) by the
208 child will still return the PID of the original parent. The
209 child is sent a SIGSTOP, but will not necessarily have stopped
210 by the completion of this call; use wait() to wait for the child
211 to stop. (addr and data are ignored.)
212 PTRACE_DETACH
214 Restarts the stopped child as for PTRACE_CONT, but first
215 detaches from the process, undoing the reparenting effect of
216 PTRACE_ATTACH, and the effects of PTRACE_TRACEME. Although per‐
217 haps not intended, under Linux a traced child can be detached in
218 this way regardless of which method was used to initiate trac‐
219 ing. (addr is ignored.)
220
222 Although arguments to ptrace() are interpreted according to the proto‐
223 type given, GNU libc currently declares ptrace() as a variadic function
224 with only the request argument fixed. This means that unneeded trail‐
225 ing arguments may be omitted, though doing so makes use of undocumented
226 gcc(1) behavior.
227 init(8), the process with PID 1, may not be traced.
229 The layout of the contents of memory and the USER area are quite OS-
231 and architecture-specific.
232 The size of a "word" is determined by the OS variant (e.g., for 32-bit
234 Linux it's 32 bits, etc.).
235 Tracing causes a few subtle differences in the semantics of traced pro‐
237 cesses. For example, if a process is attached to with PTRACE_ATTACH,
238 its original parent can no longer receive notification via wait() when
239 it stops, and there is no way for the new parent to effectively simu‐
240 late this notification.
241 When the parent receives an event with PTRACE_EVENT_* set, the child is
243 not in the normal signal delivery path. This means the parent cannot
244 do ptrace(PTRACE_CONT) with a signal or ptrace(PTRACE_KILL). kill()
245 with a SIGKILL signal can be used instead to kill the child process
246 after receiving one of these messages.
247 This page documents the way the ptrace() call works currently in Linux.
249 Its behavior differs noticeably on other flavors of Unix. In any case,
250 use of ptrace() is highly OS- and architecture-specific.
251 The SunOS man page describes ptrace() as "unique and arcane", which it
253 is. The proc-based debugging interface present in Solaris 2 implements
254 a superset of ptrace() functionality in a more powerful and uniform
255 way.
256
258 On success, PTRACE_PEEK* requests return the requested data, while
259 other requests return zero. On error, all requests return -1, and
260 errno is set appropriately. Since the value returned by a successful
261 PTRACE_PEEK* request may be -1, the caller must check errno after such
262 requests to determine whether or not an error occurred.
263
265 On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared with a
266 different value than the one for 2.4. This leads to applications com‐
267 piled with such headers failing when run on 2.4 kernels. This can be
268 worked around by redefining PTRACE_SETOPTIONS to PTRACE_OLDSETOPTIONS,
269 if that is defined.
270
272 EBUSY (i386 only) There was an error with allocating or freeing a
273 debug register.
274 EFAULT There was an attempt to read from or write to an invalid area in
276 the parent's or child's memory, probably because the area wasn't
277 mapped or accessible. Unfortunately, under Linux, different
278 variations of this fault will return EIO or EFAULT more or less
279 arbitrarily.
280 EINVAL An attempt was made to set an invalid option.
282 EIO request is invalid, or an attempt was made to read from or write
284 to an invalid area in the parent's or child's memory, or there
285 was a word-alignment violation, or an invalid signal was speci‐
286 fied during a restart request.
287 EPERM The specified process cannot be traced. This could be because
289 the parent has insufficient privileges (the required capability
290 is CAP_SYS_PTRACE); non-root processes cannot trace processes
291 that they cannot send signals to or those running set-user-
292 ID/set-group-ID programs, for obvious reasons. Alternatively,
293 the process may already be being traced, or be init (PID 1).
294 ESRCH The specified process does not exist, or is not currently being
296 traced by the caller, or is not stopped (for requests that
297 require that).
298
300 SVr4, 4.3BSD
301
303 gdb(1), strace(1), execve(2), fork(2), signal(2), wait(2), exec(3),
304 capabilities(7)
305Linux 2.6.16 2006-03-24 PTRACE(2)