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 re‐
37 sulting child do a PTRACE_TRACEME, followed (typically) by an ex‐
38 ecve(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 ig‐
49 noring the delivered signal (or even delivering a different signal in‐
50 stead).
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 re‐
68 maining requests are used only by the tracer. In the following
69 requests, pid specifies the thread ID of the tracee to be acted
70 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 re‐
77 quests 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
115 struct iovec, which describes the destination buffer's location
116 and length. On return, the kernel modifies iov.len to indicate
117 the actual number of bytes returned.
118 PTRACE_SETREGS, PTRACE_SETFPREGS
120 Modify the tracee's general-purpose or floating-point registers,
121 respectively, from the address data in the tracer. As for
122 PTRACE_POKEUSER, some general-purpose register modifications may
123 be disallowed. (addr is ignored.) Note that SPARC systems have
124 the meaning of data and addr reversed; that is, data is ignored
125 and the registers are copied from the address addr. PTRACE_SE‐
126 TREGS and PTRACE_SETFPREGS are not present on all architectures.
127 PTRACE_SETREGSET (since Linux 2.6.34)
129 Modify the tracee's registers. The meaning of addr and data is
130 analogous to PTRACE_GETREGSET.
131 PTRACE_GETSIGINFO (since Linux 2.3.99-pre6)
133 Retrieve information about the signal that caused the stop.
134 Copy a siginfo_t structure (see sigaction(2)) from the tracee to
135 the address data in the tracer. (addr is ignored.)
136 PTRACE_SETSIGINFO (since Linux 2.3.99-pre6)
138 Set signal information: copy a siginfo_t structure from the ad‐
139 dress data in the tracer to the tracee. This will affect only
140 signals that would normally be delivered to the tracee and were
141 caught by the tracer. It may be difficult to tell these normal
142 signals from synthetic signals generated by ptrace() itself.
143 (addr is ignored.)
144 PTRACE_PEEKSIGINFO (since Linux 3.10)
146 Retrieve siginfo_t structures without removing signals from a
147 queue. addr points to a ptrace_peeksiginfo_args structure that
148 specifies the ordinal position from which copying of signals
149 should start, and the number of signals to copy. siginfo_t
150 structures are copied into the buffer pointed to by data. The
151 return value contains the number of copied signals (zero indi‐
152 cates that there is no signal corresponding to the specified or‐
153 dinal position). Within the returned siginfo structures, the
154 si_code field includes information (__SI_CHLD, __SI_FAULT, etc.)
155 that are not otherwise exposed to user space.
156 struct ptrace_peeksiginfo_args {
158 u64 off; /* Ordinal position in queue at which
159 to start copying signals */
160 u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */
161 s32 nr; /* Number of signals to copy */
162 };
163 Currently, there is only one flag, PTRACE_PEEKSIGINFO_SHARED,
165 for dumping signals from the process-wide signal queue. If this
166 flag is not set, signals are read from the per-thread queue of
167 the specified thread.
168 PTRACE_GETSIGMASK (since Linux 3.11)
170 Place a copy of the mask of blocked signals (see sigprocmask(2))
171 in the buffer pointed to by data, which should be a pointer to a
172 buffer of type sigset_t. The addr argument contains the size of
173 the buffer pointed to by data (i.e., sizeof(sigset_t)).
174 PTRACE_SETSIGMASK (since Linux 3.11)
176 Change the mask of blocked signals (see sigprocmask(2)) to the
177 value specified in the buffer pointed to by data, which should
178 be a pointer to a buffer of type sigset_t. The addr argument
179 contains the size of the buffer pointed to by data (i.e.,
180 sizeof(sigset_t)).
181 PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats)
183 Set ptrace options from data. (addr is ignored.) data is in‐
184 terpreted as a bit mask of options, which are specified by the
185 following flags:
186 PTRACE_O_EXITKILL (since Linux 3.8)
188 Send a SIGKILL signal to the tracee if the tracer exits.
189 This option is useful for ptrace jailers that want to en‐
190 sure that tracees can never escape the tracer's control.
191 PTRACE_O_TRACECLONE (since Linux 2.5.46)
193 Stop the tracee at the next clone(2) and automatically
194 start tracing the newly cloned process, which will start
195 with a SIGSTOP, or PTRACE_EVENT_STOP if PTRACE_SEIZE was
196 used. A waitpid(2) by the tracer will return a status
197 value such that
198 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
200 The PID of the new process can be retrieved with
202 PTRACE_GETEVENTMSG.
203 This option may not catch clone(2) calls in all cases.
205 If the tracee calls clone(2) with the CLONE_VFORK flag,
206 PTRACE_EVENT_VFORK will be delivered instead if
207 PTRACE_O_TRACEVFORK is set; otherwise if the tracee calls
208 clone(2) with the exit signal set to SIGCHLD,
209 PTRACE_EVENT_FORK will be delivered if PTRACE_O_TRACEFORK
210 is set.
211 PTRACE_O_TRACEEXEC (since Linux 2.5.46)
213 Stop the tracee at the next execve(2). A waitpid(2) by
214 the tracer will return a status value such that
215 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
217 If the execing thread is not a thread group leader, the
219 thread ID is reset to thread group leader's ID before
220 this stop. Since Linux 3.0, the former thread ID can be
221 retrieved with PTRACE_GETEVENTMSG.
222 PTRACE_O_TRACEEXIT (since Linux 2.5.60)
224 Stop the tracee at exit. A waitpid(2) by the tracer will
225 return a status value such that
226 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
228 The tracee's exit status can be retrieved with
230 PTRACE_GETEVENTMSG.
231 The tracee is stopped early during process exit, when
233 registers are still available, allowing the tracer to see
234 where the exit occurred, whereas the normal exit notifi‐
235 cation is done after the process is finished exiting.
236 Even though context is available, the tracer cannot pre‐
237 vent the exit from happening at this point.
238 PTRACE_O_TRACEFORK (since Linux 2.5.46)
240 Stop the tracee at the next fork(2) and automatically
241 start tracing the newly forked process, which will start
242 with a SIGSTOP, or PTRACE_EVENT_STOP if PTRACE_SEIZE was
243 used. A waitpid(2) by the tracer will return a status
244 value such that
245 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
247 The PID of the new process can be retrieved with
249 PTRACE_GETEVENTMSG.
250 PTRACE_O_TRACESYSGOOD (since Linux 2.4.6)
252 When delivering system call traps, set bit 7 in the sig‐
253 nal number (i.e., deliver SIGTRAP|0x80). This makes it
254 easy for the tracer to distinguish normal traps from
255 those caused by a system call.
256 PTRACE_O_TRACEVFORK (since Linux 2.5.46)
258 Stop the tracee at the next vfork(2) and automatically
259 start tracing the newly vforked process, which will start
260 with a SIGSTOP, or PTRACE_EVENT_STOP if PTRACE_SEIZE was
261 used. A waitpid(2) by the tracer will return a status
262 value such that
263 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
265 The PID of the new process can be retrieved with
267 PTRACE_GETEVENTMSG.
268 PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60)
270 Stop the tracee at the completion of the next vfork(2).
271 A waitpid(2) by the tracer will return a status value
272 such that
273 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
275 The PID of the new process can (since Linux 2.6.18) be
277 retrieved with PTRACE_GETEVENTMSG.
278 PTRACE_O_TRACESECCOMP (since Linux 3.5)
280 Stop the tracee when a seccomp(2) SECCOMP_RET_TRACE rule
281 is triggered. A waitpid(2) by the tracer will return a
282 status value such that
283 status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))
285 While this triggers a PTRACE_EVENT stop, it is similar to
287 a syscall-enter-stop. For details, see the note on
288 PTRACE_EVENT_SECCOMP below. The seccomp event message
289 data (from the SECCOMP_RET_DATA portion of the seccomp
290 filter rule) can be retrieved with PTRACE_GETEVENTMSG.
291 PTRACE_O_SUSPEND_SECCOMP (since Linux 4.3)
293 Suspend the tracee's seccomp protections. This applies
294 regardless of mode, and can be used when the tracee has
295 not yet installed seccomp filters. That is, a valid use
296 case is to suspend a tracee's seccomp protections before
297 they are installed by the tracee, let the tracee install
298 the filters, and then clear this flag when the filters
299 should be resumed. Setting this option requires that the
300 tracer have the CAP_SYS_ADMIN capability, not have any
301 seccomp protections installed, and not have PTRACE_O_SUS‐
302 PEND_SECCOMP set on itself.
303 PTRACE_GETEVENTMSG (since Linux 2.5.46)
305 Retrieve a message (as an unsigned long) about the ptrace event
306 that just happened, placing it at the address data in the
307 tracer. For PTRACE_EVENT_EXIT, this is the tracee's exit sta‐
308 tus. For PTRACE_EVENT_FORK, PTRACE_EVENT_VFORK,
309 PTRACE_EVENT_VFORK_DONE, and PTRACE_EVENT_CLONE, this is the PID
310 of the new process. For PTRACE_EVENT_SECCOMP, this is the sec‐
311 comp(2) filter's SECCOMP_RET_DATA associated with the triggered
312 rule. (addr is ignored.)
313 PTRACE_CONT
315 Restart the stopped tracee process. If data is nonzero, it is
316 interpreted as the number of a signal to be delivered to the
317 tracee; otherwise, no signal is delivered. Thus, for example,
318 the tracer can control whether a signal sent to the tracee is
319 delivered or not. (addr is ignored.)
320 PTRACE_SYSCALL, PTRACE_SINGLESTEP
322 Restart the stopped tracee as for PTRACE_CONT, but arrange for
323 the tracee to be stopped at the next entry to or exit from a
324 system call, or after execution of a single instruction, respec‐
325 tively. (The tracee will also, as usual, be stopped upon re‐
326 ceipt of a signal.) From the tracer's perspective, the tracee
327 will appear to have been stopped by receipt of a SIGTRAP. So,
328 for PTRACE_SYSCALL, for example, the idea is to inspect the ar‐
329 guments to the system call at the first stop, then do another
330 PTRACE_SYSCALL and inspect the return value of the system call
331 at the second stop. The data argument is treated as for
332 PTRACE_CONT. (addr is ignored.)
333 PTRACE_SET_SYSCALL (since Linux 2.6.16)
335 When in syscall-enter-stop, change the number of the system call
336 that is about to be executed to the number specified in the data
337 argument. The addr argument is ignored. This request is cur‐
338 rently supported only on arm (and arm64, though only for back‐
339 wards compatibility), but most other architectures have other
340 means of accomplishing this (usually by changing the register
341 that the userland code passed the system call number in).
342 PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14)
344 For PTRACE_SYSEMU, continue and stop on entry to the next system
345 call, which will not be executed. See the documentation on
346 syscall-stops below. For PTRACE_SYSEMU_SINGLESTEP, do the same
347 but also singlestep if not a system call. This call is used by
348 programs like User Mode Linux that want to emulate all the
349 tracee's system calls. The data argument is treated as for
350 PTRACE_CONT. The addr argument is ignored. These requests are
351 currently supported only on x86.
352 PTRACE_LISTEN (since Linux 3.4)
354 Restart the stopped tracee, but prevent it from executing. The
355 resulting state of the tracee is similar to a process which has
356 been stopped by a SIGSTOP (or other stopping signal). See the
357 "group-stop" subsection for additional information. PTRACE_LIS‐
358 TEN works only on tracees attached by PTRACE_SEIZE.
359 PTRACE_KILL
361 Send the tracee a SIGKILL to terminate it. (addr and data are
362 ignored.)
363 This operation is deprecated; do not use it! Instead, send a
365 SIGKILL directly using kill(2) or tgkill(2). The problem with
366 PTRACE_KILL is that it requires the tracee to be in signal-de‐
367 livery-stop, otherwise it may not work (i.e., may complete suc‐
368 cessfully but won't kill the tracee). By contrast, sending a
369 SIGKILL directly has no such limitation.
370 PTRACE_INTERRUPT (since Linux 3.4)
372 Stop a tracee. If the tracee is running or sleeping in kernel
373 space and PTRACE_SYSCALL is in effect, the system call is inter‐
374 rupted and syscall-exit-stop is reported. (The interrupted sys‐
375 tem call is restarted when the tracee is restarted.) If the
376 tracee was already stopped by a signal and PTRACE_LISTEN was
377 sent to it, the tracee stops with PTRACE_EVENT_STOP and WSTOP‐
378 SIG(status) returns the stop signal. If any other ptrace-stop
379 is generated at the same time (for example, if a signal is sent
380 to the tracee), this ptrace-stop happens. If none of the above
381 applies (for example, if the tracee is running in user space),
382 it stops with PTRACE_EVENT_STOP with WSTOPSIG(status) == SIG‐
383 TRAP. PTRACE_INTERRUPT only works on tracees attached by
384 PTRACE_SEIZE.
385 PTRACE_ATTACH
387 Attach to the process specified in pid, making it a tracee of
388 the calling process. The tracee is sent a SIGSTOP, but will not
389 necessarily have stopped by the completion of this call; use
390 waitpid(2) to wait for the tracee to stop. See the "Attaching
391 and detaching" subsection for additional information. (addr and
392 data are ignored.)
393 Permission to perform a PTRACE_ATTACH is governed by a ptrace
395 access mode PTRACE_MODE_ATTACH_REALCREDS check; see below.
396 PTRACE_SEIZE (since Linux 3.4)
398 Attach to the process specified in pid, making it a tracee of
399 the calling process. Unlike PTRACE_ATTACH, PTRACE_SEIZE does
400 not stop the process. Group-stops are reported as
401 PTRACE_EVENT_STOP and WSTOPSIG(status) returns the stop signal.
402 Automatically attached children stop with PTRACE_EVENT_STOP and
403 WSTOPSIG(status) returns SIGTRAP instead of having SIGSTOP sig‐
404 nal delivered to them. execve(2) does not deliver an extra SIG‐
405 TRAP. Only a PTRACE_SEIZEd process can accept PTRACE_INTERRUPT
406 and PTRACE_LISTEN commands. The "seized" behavior just de‐
407 scribed is inherited by children that are automatically attached
408 using PTRACE_O_TRACEFORK, PTRACE_O_TRACEVFORK, and
409 PTRACE_O_TRACECLONE. addr must be zero. data contains a bit
410 mask of ptrace options to activate immediately.
411 Permission to perform a PTRACE_SEIZE is governed by a ptrace ac‐
413 cess mode PTRACE_MODE_ATTACH_REALCREDS check; see below.
414 PTRACE_SECCOMP_GET_FILTER (since Linux 4.4)
416 This operation allows the tracer to dump the tracee's classic
417 BPF filters.
418 addr is an integer specifying the index of the filter to be
420 dumped. The most recently installed filter has the index 0. If
421 addr is greater than the number of installed filters, the opera‐
422 tion fails with the error ENOENT.
423 data is either a pointer to a struct sock_filter array that is
425 large enough to store the BPF program, or NULL if the program is
426 not to be stored.
427 Upon success, the return value is the number of instructions in
429 the BPF program. If data was NULL, then this return value can
430 be used to correctly size the struct sock_filter array passed in
431 a subsequent call.
432 This operation fails with the error EACCES if the caller does
434 not have the CAP_SYS_ADMIN capability or if the caller is in
435 strict or filter seccomp mode. If the filter referred to by
436 addr is not a classic BPF filter, the operation fails with the
437 error EMEDIUMTYPE.
438 This operation is available if the kernel was configured with
440 both the CONFIG_SECCOMP_FILTER and the CONFIG_CHECKPOINT_RESTORE
441 options.
442 PTRACE_DETACH
444 Restart the stopped tracee as for PTRACE_CONT, but first detach
445 from it. Under Linux, a tracee can be detached in this way re‐
446 gardless of which method was used to initiate tracing. (addr is
447 ignored.)
448 PTRACE_GET_THREAD_AREA (since Linux 2.6.0)
450 This operation performs a similar task to get_thread_area(2).
451 It reads the TLS entry in the GDT whose index is given in addr,
452 placing a copy of the entry into the struct user_desc pointed to
453 by data. (By contrast with get_thread_area(2), the entry_number
454 of the struct user_desc is ignored.)
455 PTRACE_SET_THREAD_AREA (since Linux 2.6.0)
457 This operation performs a similar task to set_thread_area(2).
458 It sets the TLS entry in the GDT whose index is given in addr,
459 assigning it the data supplied in the struct user_desc pointed
460 to by data. (By contrast with set_thread_area(2), the en‐
461 try_number of the struct user_desc is ignored; in other words,
462 this ptrace operation can't be used to allocate a free TLS en‐
463 try.)
464 PTRACE_GET_SYSCALL_INFO (since Linux 5.3)
466 Retrieve information about the system call that caused the stop.
467 The information is placed into the buffer pointed by the data
468 argument, which should be a pointer to a buffer of type struct
469 ptrace_syscall_info. The addr argument contains the size of the
470 buffer pointed to by the data argument (i.e., sizeof(struct
471 ptrace_syscall_info)). The return value contains the number of
472 bytes available to be written by the kernel. If the size of the
473 data to be written by the kernel exceeds the size specified by
474 the addr argument, the output data is truncated.
475 The ptrace_syscall_info structure contains the following fields:
477 struct ptrace_syscall_info {
479 __u8 op; /* Type of system call stop */
480 __u32 arch; /* AUDIT_ARCH_* value; see seccomp(2) */
481 __u64 instruction_pointer; /* CPU instruction pointer */
482 __u64 stack_pointer; /* CPU stack pointer */
483 union {
484 struct { /* op == PTRACE_SYSCALL_INFO_ENTRY */
485 __u64 nr; /* System call number */
486 __u64 args[6]; /* System call arguments */
487 } entry;
488 struct { /* op == PTRACE_SYSCALL_INFO_EXIT */
489 __s64 rval; /* System call return value */
490 __u8 is_error; /* System call error flag;
491 Boolean: does rval contain
492 an error value (-ERRCODE) or
493 a nonerror return value? */
494 } exit;
495 struct { /* op == PTRACE_SYSCALL_INFO_SECCOMP */
496 __u64 nr; /* System call number */
497 __u64 args[6]; /* System call arguments */
498 __u32 ret_data; /* SECCOMP_RET_DATA portion
499 of SECCOMP_RET_TRACE
500 return value */
501 } seccomp;
502 };
503 };
504 The op, arch, instruction_pointer, and stack_pointer fields are
506 defined for all kinds of ptrace system call stops. The rest of
507 the structure is a union; one should read only those fields that
508 are meaningful for the kind of system call stop specified by the
509 op field.
510 The op field has one of the following values (defined in
512 <linux/ptrace.h>) indicating what type of stop occurred and
513 which part of the union is filled:
514 PTRACE_SYSCALL_INFO_ENTRY
516 The entry component of the union contains information re‐
517 lating to a system call entry stop.
518 PTRACE_SYSCALL_INFO_EXIT
520 The exit component of the union contains information re‐
521 lating to a system call exit stop.
522 PTRACE_SYSCALL_INFO_SECCOMP
524 The seccomp component of the union contains information
525 relating to a PTRACE_EVENT_SECCOMP stop.
526 PTRACE_SYSCALL_INFO_NONE
528 No component of the union contains relevant information.
529 Death under ptrace
531 When a (possibly multithreaded) process receives a killing signal (one
532 whose disposition is set to SIG_DFL and whose default action is to kill
533 the process), all threads exit. Tracees report their death to their
534 tracer(s). Notification of this event is delivered via waitpid(2).
535 Note that the killing signal will first cause signal-delivery-stop (on
537 one tracee only), and only after it is injected by the tracer (or after
538 it was dispatched to a thread which isn't traced), will death from the
539 signal happen on all tracees within a multithreaded process. (The term
540 "signal-delivery-stop" is explained below.)
541 SIGKILL does not generate signal-delivery-stop and therefore the tracer
543 can't suppress it. SIGKILL kills even within system calls (syscall-
544 exit-stop is not generated prior to death by SIGKILL). The net effect
545 is that SIGKILL always kills the process (all its threads), even if
546 some threads of the process are ptraced.
547 When the tracee calls _exit(2), it reports its death to its tracer.
549 Other threads are not affected.
550 When any thread executes exit_group(2), every tracee in its thread
552 group reports its death to its tracer.
553 If the PTRACE_O_TRACEEXIT option is on, PTRACE_EVENT_EXIT will happen
555 before actual death. This applies to exits via exit(2), exit_group(2),
556 and signal deaths (except SIGKILL, depending on the kernel version; see
557 BUGS below), and when threads are torn down on execve(2) in a multi‐
558 threaded process.
559 The tracer cannot assume that the ptrace-stopped tracee exists. There
561 are many scenarios when the tracee may die while stopped (such as
562 SIGKILL). Therefore, the tracer must be prepared to handle an ESRCH
563 error on any ptrace operation. Unfortunately, the same error is re‐
564 turned if the tracee exists but is not ptrace-stopped (for commands
565 which require a stopped tracee), or if it is not traced by the process
566 which issued the ptrace call. The tracer needs to keep track of the
567 stopped/running state of the tracee, and interpret ESRCH as "tracee
568 died unexpectedly" only if it knows that the tracee has been observed
569 to enter ptrace-stop. Note that there is no guarantee that wait‐
570 pid(WNOHANG) will reliably report the tracee's death status if a ptrace
571 operation returned ESRCH. waitpid(WNOHANG) may return 0 instead. In
572 other words, the tracee may be "not yet fully dead", but already refus‐
573 ing ptrace requests.
574 The tracer can't assume that the tracee always ends its life by report‐
576 ing WIFEXITED(status) or WIFSIGNALED(status); there are cases where
577 this does not occur. For example, if a thread other than thread group
578 leader does an execve(2), it disappears; its PID will never be seen
579 again, and any subsequent ptrace stops will be reported under the
580 thread group leader's PID.
581 Stopped states
583 A tracee can be in two states: running or stopped. For the purposes of
584 ptrace, a tracee which is blocked in a system call (such as read(2),
585 pause(2), etc.) is nevertheless considered to be running, even if the
586 tracee is blocked for a long time. The state of the tracee after
587 PTRACE_LISTEN is somewhat of a gray area: it is not in any ptrace-stop
588 (ptrace commands won't work on it, and it will deliver waitpid(2) noti‐
589 fications), but it also may be considered "stopped" because it is not
590 executing instructions (is not scheduled), and if it was in group-stop
591 before PTRACE_LISTEN, it will not respond to signals until SIGCONT is
592 received.
593 There are many kinds of states when the tracee is stopped, and in
595 ptrace discussions they are often conflated. Therefore, it is impor‐
596 tant to use precise terms.
597 In this manual page, any stopped state in which the tracee is ready to
599 accept ptrace commands from the tracer is called ptrace-stop. Ptrace-
600 stops can be further subdivided into signal-delivery-stop, group-stop,
601 syscall-stop, PTRACE_EVENT stops, and so on. These stopped states are
602 described in detail below.
603 When the running tracee enters ptrace-stop, it notifies its tracer us‐
605 ing waitpid(2) (or one of the other "wait" system calls). Most of this
606 manual page assumes that the tracer waits with:
607 pid = waitpid(pid_or_minus_1, &status, __WALL);
609 Ptrace-stopped tracees are reported as returns with pid greater than 0
611 and WIFSTOPPED(status) true.
612 The __WALL flag does not include the WSTOPPED and WEXITED flags, but
614 implies their functionality.
615 Setting the WCONTINUED flag when calling waitpid(2) is not recommended:
617 the "continued" state is per-process and consuming it can confuse the
618 real parent of the tracee.
619 Use of the WNOHANG flag may cause waitpid(2) to return 0 ("no wait re‐
621 sults available yet") even if the tracer knows there should be a noti‐
622 fication. Example:
623 errno = 0;
625 ptrace(PTRACE_CONT, pid, 0L, 0L);
626 if (errno == ESRCH) {
627 /* tracee is dead */
628 r = waitpid(tracee, &status, __WALL | WNOHANG);
629 /* r can still be 0 here! */
630 }
631 The following kinds of ptrace-stops exist: signal-delivery-stops,
633 group-stops, PTRACE_EVENT stops, syscall-stops. They all are reported
634 by waitpid(2) with WIFSTOPPED(status) true. They may be differentiated
635 by examining the value status>>8, and if there is ambiguity in that
636 value, by querying PTRACE_GETSIGINFO. (Note: the WSTOPSIG(status)
637 macro can't be used to perform this examination, because it returns the
638 value (status>>8) & 0xff.)
639 Signal-delivery-stop
641 When a (possibly multithreaded) process receives any signal except
642 SIGKILL, the kernel selects an arbitrary thread which handles the sig‐
643 nal. (If the signal is generated with tgkill(2), the target thread can
644 be explicitly selected by the caller.) If the selected thread is
645 traced, it enters signal-delivery-stop. At this point, the signal is
646 not yet delivered to the process, and can be suppressed by the tracer.
647 If the tracer doesn't suppress the signal, it passes the signal to the
648 tracee in the next ptrace restart request. This second step of signal
649 delivery is called signal injection in this manual page. Note that if
650 the signal is blocked, signal-delivery-stop doesn't happen until the
651 signal is unblocked, with the usual exception that SIGSTOP can't be
652 blocked.
653 Signal-delivery-stop is observed by the tracer as waitpid(2) returning
655 with WIFSTOPPED(status) true, with the signal returned by WSTOPSIG(sta‐
656 tus). If the signal is SIGTRAP, this may be a different kind of
657 ptrace-stop; see the "Syscall-stops" and "execve" sections below for
658 details. If WSTOPSIG(status) returns a stopping signal, this may be a
659 group-stop; see below.
660 Signal injection and suppression
662 After signal-delivery-stop is observed by the tracer, the tracer should
663 restart the tracee with the call
664 ptrace(PTRACE_restart, pid, 0, sig)
666 where PTRACE_restart is one of the restarting ptrace requests. If sig
668 is 0, then a signal is not delivered. Otherwise, the signal sig is de‐
669 livered. This operation is called signal injection in this manual
670 page, to distinguish it from signal-delivery-stop.
671 The sig value may be different from the WSTOPSIG(status) value: the
673 tracer can cause a different signal to be injected.
674 Note that a suppressed signal still causes system calls to return pre‐
676 maturely. In this case, system calls will be restarted: the tracer
677 will observe the tracee to reexecute the interrupted system call (or
678 restart_syscall(2) system call for a few system calls which use a dif‐
679 ferent mechanism for restarting) if the tracer uses PTRACE_SYSCALL.
680 Even system calls (such as poll(2)) which are not restartable after
681 signal are restarted after signal is suppressed; however, kernel bugs
682 exist which cause some system calls to fail with EINTR even though no
683 observable signal is injected to the tracee.
684 Restarting ptrace commands issued in ptrace-stops other than signal-de‐
686 livery-stop are not guaranteed to inject a signal, even if sig is non‐
687 zero. No error is reported; a nonzero sig may simply be ignored.
688 Ptrace users should not try to "create a new signal" this way: use
689 tgkill(2) instead.
690 The fact that signal injection requests may be ignored when restarting
692 the tracee after ptrace stops that are not signal-delivery-stops is a
693 cause of confusion among ptrace users. One typical scenario is that
694 the tracer observes group-stop, mistakes it for signal-delivery-stop,
695 restarts the tracee with
696 ptrace(PTRACE_restart, pid, 0, stopsig)
698 with the intention of injecting stopsig, but stopsig gets ignored and
700 the tracee continues to run.
701 The SIGCONT signal has a side effect of waking up (all threads of) a
703 group-stopped process. This side effect happens before signal-deliv‐
704 ery-stop. The tracer can't suppress this side effect (it can only sup‐
705 press signal injection, which only causes the SIGCONT handler to not be
706 executed in the tracee, if such a handler is installed). In fact, wak‐
707 ing up from group-stop may be followed by signal-delivery-stop for sig‐
708 nal(s) other than SIGCONT, if they were pending when SIGCONT was deliv‐
709 ered. In other words, SIGCONT may be not the first signal observed by
710 the tracee after it was sent.
711 Stopping signals cause (all threads of) a process to enter group-stop.
713 This side effect happens after signal injection, and therefore can be
714 suppressed by the tracer.
715 In Linux 2.4 and earlier, the SIGSTOP signal can't be injected.
717 PTRACE_GETSIGINFO can be used to retrieve a siginfo_t structure which
719 corresponds to the delivered signal. PTRACE_SETSIGINFO may be used to
720 modify it. If PTRACE_SETSIGINFO has been used to alter siginfo_t, the
721 si_signo field and the sig parameter in the restarting command must
722 match, otherwise the result is undefined.
723 Group-stop
725 When a (possibly multithreaded) process receives a stopping signal, all
726 threads stop. If some threads are traced, they enter a group-stop.
727 Note that the stopping signal will first cause signal-delivery-stop (on
728 one tracee only), and only after it is injected by the tracer (or after
729 it was dispatched to a thread which isn't traced), will group-stop be
730 initiated on all tracees within the multithreaded process. As usual,
731 every tracee reports its group-stop separately to the corresponding
732 tracer.
733 Group-stop is observed by the tracer as waitpid(2) returning with WIF‐
735 STOPPED(status) true, with the stopping signal available via WSTOP‐
736 SIG(status). The same result is returned by some other classes of
737 ptrace-stops, therefore the recommended practice is to perform the call
738 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
740 The call can be avoided if the signal is not SIGSTOP, SIGTSTP, SIGTTIN,
742 or SIGTTOU; only these four signals are stopping signals. If the
743 tracer sees something else, it can't be a group-stop. Otherwise, the
744 tracer needs to call PTRACE_GETSIGINFO. If PTRACE_GETSIGINFO fails
745 with EINVAL, then it is definitely a group-stop. (Other failure codes
746 are possible, such as ESRCH ("no such process") if a SIGKILL killed the
747 tracee.)
748 If tracee was attached using PTRACE_SEIZE, group-stop is indicated by
750 PTRACE_EVENT_STOP: status>>16 == PTRACE_EVENT_STOP. This allows detec‐
751 tion of group-stops without requiring an extra PTRACE_GETSIGINFO call.
752 As of Linux 2.6.38, after the tracer sees the tracee ptrace-stop and
754 until it restarts or kills it, the tracee will not run, and will not
755 send notifications (except SIGKILL death) to the tracer, even if the
756 tracer enters into another waitpid(2) call.
757 The kernel behavior described in the previous paragraph causes a prob‐
759 lem with transparent handling of stopping signals. If the tracer
760 restarts the tracee after group-stop, the stopping signal is effec‐
761 tively ignored—the tracee doesn't remain stopped, it runs. If the
762 tracer doesn't restart the tracee before entering into the next wait‐
763 pid(2), future SIGCONT signals will not be reported to the tracer; this
764 would cause the SIGCONT signals to have no effect on the tracee.
765 Since Linux 3.4, there is a method to overcome this problem: instead of
767 PTRACE_CONT, a PTRACE_LISTEN command can be used to restart a tracee in
768 a way where it does not execute, but waits for a new event which it can
769 report via waitpid(2) (such as when it is restarted by a SIGCONT).
770 PTRACE_EVENT stops
772 If the tracer sets PTRACE_O_TRACE_* options, the tracee will enter
773 ptrace-stops called PTRACE_EVENT stops.
774 PTRACE_EVENT stops are observed by the tracer as waitpid(2) returning
776 with WIFSTOPPED(status), and WSTOPSIG(status) returns SIGTRAP (or for
777 PTRACE_EVENT_STOP, returns the stopping signal if tracee is in a group-
778 stop). An additional bit is set in the higher byte of the status word:
779 the value status>>8 will be
780 ((PTRACE_EVENT_foo<<8) | SIGTRAP).
782 The following events exist:
784 PTRACE_EVENT_VFORK
786 Stop before return from vfork(2) or clone(2) with the
787 CLONE_VFORK flag. When the tracee is continued after this stop,
788 it will wait for child to exit/exec before continuing its execu‐
789 tion (in other words, the usual behavior on vfork(2)).
790 PTRACE_EVENT_FORK
792 Stop before return from fork(2) or clone(2) with the exit signal
793 set to SIGCHLD.
794 PTRACE_EVENT_CLONE
796 Stop before return from clone(2).
797 PTRACE_EVENT_VFORK_DONE
799 Stop before return from vfork(2) or clone(2) with the
800 CLONE_VFORK flag, but after the child unblocked this tracee by
801 exiting or execing.
802 For all four stops described above, the stop occurs in the parent
804 (i.e., the tracee), not in the newly created thread.
805 PTRACE_GETEVENTMSG can be used to retrieve the new thread's ID.
806 PTRACE_EVENT_EXEC
808 Stop before return from execve(2). Since Linux 3.0,
809 PTRACE_GETEVENTMSG returns the former thread ID.
810 PTRACE_EVENT_EXIT
812 Stop before exit (including death from exit_group(2)), signal
813 death, or exit caused by execve(2) in a multithreaded process.
814 PTRACE_GETEVENTMSG returns the exit status. Registers can be
815 examined (unlike when "real" exit happens). The tracee is still
816 alive; it needs to be PTRACE_CONTed or PTRACE_DETACHed to finish
817 exiting.
818 PTRACE_EVENT_STOP
820 Stop induced by PTRACE_INTERRUPT command, or group-stop, or ini‐
821 tial ptrace-stop when a new child is attached (only if attached
822 using PTRACE_SEIZE).
823 PTRACE_EVENT_SECCOMP
825 Stop triggered by a seccomp(2) rule on tracee syscall entry when
826 PTRACE_O_TRACESECCOMP has been set by the tracer. The seccomp
827 event message data (from the SECCOMP_RET_DATA portion of the
828 seccomp filter rule) can be retrieved with PTRACE_GETEVENTMSG.
829 The semantics of this stop are described in detail in a separate
830 section below.
831 PTRACE_GETSIGINFO on PTRACE_EVENT stops returns SIGTRAP in si_signo,
833 with si_code set to (event<<8) | SIGTRAP.
834 Syscall-stops
836 If the tracee was restarted by PTRACE_SYSCALL or PTRACE_SYSEMU, the
837 tracee enters syscall-enter-stop just prior to entering any system call
838 (which will not be executed if the restart was using PTRACE_SYSEMU, re‐
839 gardless of any change made to registers at this point or how the
840 tracee is restarted after this stop). No matter which method caused
841 the syscall-entry-stop, if the tracer restarts the tracee with
842 PTRACE_SYSCALL, the tracee enters syscall-exit-stop when the system
843 call is finished, or if it is interrupted by a signal. (That is, sig‐
844 nal-delivery-stop never happens between syscall-enter-stop and syscall-
845 exit-stop; it happens after syscall-exit-stop.). If the tracee is con‐
846 tinued using any other method (including PTRACE_SYSEMU), no syscall-
847 exit-stop occurs. Note that all mentions PTRACE_SYSEMU apply equally
848 to PTRACE_SYSEMU_SINGLESTEP.
849 However, even if the tracee was continued using PTRACE_SYSCALL, it is
851 not guaranteed that the next stop will be a syscall-exit-stop. Other
852 possibilities are that the tracee may stop in a PTRACE_EVENT stop (in‐
853 cluding seccomp stops), exit (if it entered _exit(2) or exit_group(2)),
854 be killed by SIGKILL, or die silently (if it is a thread group leader,
855 the execve(2) happened in another thread, and that thread is not traced
856 by the same tracer; this situation is discussed later).
857 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
859 waitpid(2) returning with WIFSTOPPED(status) true, and WSTOPSIG(status)
860 giving SIGTRAP. If the PTRACE_O_TRACESYSGOOD option was set by the
861 tracer, then WSTOPSIG(status) will give the value (SIGTRAP | 0x80).
862 Syscall-stops can be distinguished from signal-delivery-stop with SIG‐
864 TRAP by querying PTRACE_GETSIGINFO for the following cases:
865 si_code <= 0
867 SIGTRAP was delivered as a result of a user-space action, for
868 example, a system call (tgkill(2), kill(2), sigqueue(3), etc.),
869 expiration of a POSIX timer, change of state on a POSIX message
870 queue, or completion of an asynchronous I/O request.
871 si_code == SI_KERNEL (0x80)
873 SIGTRAP was sent by the kernel.
874 si_code == SIGTRAP or si_code == (SIGTRAP|0x80)
876 This is a syscall-stop.
877 However, syscall-stops happen very often (twice per system call), and
879 performing PTRACE_GETSIGINFO for every syscall-stop may be somewhat ex‐
880 pensive.
881 Some architectures allow the cases to be distinguished by examining
883 registers. For example, on x86, rax == -ENOSYS in syscall-enter-stop.
884 Since SIGTRAP (like any other signal) always happens after syscall-
885 exit-stop, and at this point rax almost never contains -ENOSYS, the
886 SIGTRAP looks like "syscall-stop which is not syscall-enter-stop"; in
887 other words, it looks like a "stray syscall-exit-stop" and can be de‐
888 tected this way. But such detection is fragile and is best avoided.
889 Using the PTRACE_O_TRACESYSGOOD option is the recommended method to
891 distinguish syscall-stops from other kinds of ptrace-stops, since it is
892 reliable and does not incur a performance penalty.
893 Syscall-enter-stop and syscall-exit-stop are indistinguishable from
895 each other by the tracer. The tracer needs to keep track of the se‐
896 quence of ptrace-stops in order to not misinterpret syscall-enter-stop
897 as syscall-exit-stop or vice versa. In general, a syscall-enter-stop
898 is always followed by syscall-exit-stop, PTRACE_EVENT stop, or the
899 tracee's death; no other kinds of ptrace-stop can occur in between.
900 However, note that seccomp stops (see below) can cause syscall-exit-
901 stops, without preceding syscall-entry-stops. If seccomp is in use,
902 care needs to be taken not to misinterpret such stops as syscall-entry-
903 stops.
904 If after syscall-enter-stop, the tracer uses a restarting command other
906 than PTRACE_SYSCALL, syscall-exit-stop is not generated.
907 PTRACE_GETSIGINFO on syscall-stops returns SIGTRAP in si_signo, with
909 si_code set to SIGTRAP or (SIGTRAP|0x80).
910 PTRACE_EVENT_SECCOMP stops (Linux 3.5 to 4.7)
912 The behavior of PTRACE_EVENT_SECCOMP stops and their interaction with
913 other kinds of ptrace stops has changed between kernel versions. This
914 documents the behavior from their introduction until Linux 4.7 (inclu‐
915 sive). The behavior in later kernel versions is documented in the next
916 section.
917 A PTRACE_EVENT_SECCOMP stop occurs whenever a SECCOMP_RET_TRACE rule is
919 triggered. This is independent of which methods was used to restart
920 the system call. Notably, seccomp still runs even if the tracee was
921 restarted using PTRACE_SYSEMU and this system call is unconditionally
922 skipped.
923 Restarts from this stop will behave as if the stop had occurred right
925 before the system call in question. In particular, both PTRACE_SYSCALL
926 and PTRACE_SYSEMU will normally cause a subsequent syscall-entry-stop.
927 However, if after the PTRACE_EVENT_SECCOMP the system call number is
928 negative, both the syscall-entry-stop and the system call itself will
929 be skipped. This means that if the system call number is negative af‐
930 ter a PTRACE_EVENT_SECCOMP and the tracee is restarted using
931 PTRACE_SYSCALL, the next observed stop will be a syscall-exit-stop,
932 rather than the syscall-entry-stop that might have been expected.
933 PTRACE_EVENT_SECCOMP stops (since Linux 4.8)
935 Starting with Linux 4.8, the PTRACE_EVENT_SECCOMP stop was reordered to
936 occur between syscall-entry-stop and syscall-exit-stop. Note that sec‐
937 comp no longer runs (and no PTRACE_EVENT_SECCOMP will be reported) if
938 the system call is skipped due to PTRACE_SYSEMU.
939 Functionally, a PTRACE_EVENT_SECCOMP stop functions comparably to a
941 syscall-entry-stop (i.e., continuations using PTRACE_SYSCALL will cause
942 syscall-exit-stops, the system call number may be changed and any other
943 modified registers are visible to the to-be-executed system call as
944 well). Note that there may be, but need not have been a preceding
945 syscall-entry-stop.
946 After a PTRACE_EVENT_SECCOMP stop, seccomp will be rerun, with a SEC‐
948 COMP_RET_TRACE rule now functioning the same as a SECCOMP_RET_ALLOW.
949 Specifically, this means that if registers are not modified during the
950 PTRACE_EVENT_SECCOMP stop, the system call will then be allowed.
951 PTRACE_SINGLESTEP stops
953 [Details of these kinds of stops are yet to be documented.]
954 Informational and restarting ptrace commands
956 Most ptrace commands (all except PTRACE_ATTACH, PTRACE_SEIZE,
957 PTRACE_TRACEME, PTRACE_INTERRUPT, and PTRACE_KILL) require the tracee
958 to be in a ptrace-stop, otherwise they fail with ESRCH.
959 When the tracee is in ptrace-stop, the tracer can read and write data
961 to the tracee using informational commands. These commands leave the
962 tracee in ptrace-stopped state:
963 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
965 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
966 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
967 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
968 ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
969 ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
970 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
971 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
972 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
973 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
974 Note that some errors are not reported. For example, setting signal
976 information (siginfo) may have no effect in some ptrace-stops, yet the
977 call may succeed (return 0 and not set errno); querying
978 PTRACE_GETEVENTMSG may succeed and return some random value if current
979 ptrace-stop is not documented as returning a meaningful event message.
980 The call
982 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
984 affects one tracee. The tracee's current flags are replaced. Flags
986 are inherited by new tracees created and "auto-attached" via active
987 PTRACE_O_TRACEFORK, PTRACE_O_TRACEVFORK, or PTRACE_O_TRACECLONE op‐
988 tions.
989 Another group of commands makes the ptrace-stopped tracee run. They
991 have the form:
992 ptrace(cmd, pid, 0, sig);
994 where cmd is PTRACE_CONT, PTRACE_LISTEN, PTRACE_DETACH, PTRACE_SYSCALL,
996 PTRACE_SINGLESTEP, PTRACE_SYSEMU, or PTRACE_SYSEMU_SINGLESTEP. If the
997 tracee is in signal-delivery-stop, sig is the signal to be injected (if
998 it is nonzero). Otherwise, sig may be ignored. (When restarting a
999 tracee from a ptrace-stop other than signal-delivery-stop, recommended
1000 practice is to always pass 0 in sig.)
1001 Attaching and detaching
1003 A thread can be attached to the tracer using the call
1004 ptrace(PTRACE_ATTACH, pid, 0, 0);
1006 or
1008 ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
1010 PTRACE_ATTACH sends SIGSTOP to this thread. If the tracer wants this
1012 SIGSTOP to have no effect, it needs to suppress it. Note that if other
1013 signals are concurrently sent to this thread during attach, the tracer
1014 may see the tracee enter signal-delivery-stop with other signal(s)
1015 first! The usual practice is to reinject these signals until SIGSTOP
1016 is seen, then suppress SIGSTOP injection. The design bug here is that
1017 a ptrace attach and a concurrently delivered SIGSTOP may race and the
1018 concurrent SIGSTOP may be lost.
1019 Since attaching sends SIGSTOP and the tracer usually suppresses it,
1021 this may cause a stray EINTR return from the currently executing system
1022 call in the tracee, as described in the "Signal injection and suppres‐
1023 sion" section.
1024 Since Linux 3.4, PTRACE_SEIZE can be used instead of PTRACE_ATTACH.
1026 PTRACE_SEIZE does not stop the attached process. If you need to stop
1027 it after attach (or at any other time) without sending it any signals,
1028 use PTRACE_INTERRUPT command.
1029 The request
1031 ptrace(PTRACE_TRACEME, 0, 0, 0);
1033 turns the calling thread into a tracee. The thread continues to run
1035 (doesn't enter ptrace-stop). A common practice is to follow the
1036 PTRACE_TRACEME with
1037 raise(SIGSTOP);
1039 and allow the parent (which is our tracer now) to observe our signal-
1041 delivery-stop.
1042 If the PTRACE_O_TRACEFORK, PTRACE_O_TRACEVFORK, or PTRACE_O_TRACECLONE
1044 options are in effect, then children created by, respectively, vfork(2)
1045 or clone(2) with the CLONE_VFORK flag, fork(2) or clone(2) with the
1046 exit signal set to SIGCHLD, and other kinds of clone(2), are automati‐
1047 cally attached to the same tracer which traced their parent. SIGSTOP
1048 is delivered to the children, causing them to enter signal-delivery-
1049 stop after they exit the system call which created them.
1050 Detaching of the tracee is performed by:
1052 ptrace(PTRACE_DETACH, pid, 0, sig);
1054 PTRACE_DETACH is a restarting operation; therefore it requires the
1056 tracee to be in ptrace-stop. If the tracee is in signal-delivery-stop,
1057 a signal can be injected. Otherwise, the sig parameter may be silently
1058 ignored.
1059 If the tracee is running when the tracer wants to detach it, the usual
1061 solution is to send SIGSTOP (using tgkill(2), to make sure it goes to
1062 the correct thread), wait for the tracee to stop in signal-delivery-
1063 stop for SIGSTOP and then detach it (suppressing SIGSTOP injection). A
1064 design bug is that this can race with concurrent SIGSTOPs. Another
1065 complication is that the tracee may enter other ptrace-stops and needs
1066 to be restarted and waited for again, until SIGSTOP is seen. Yet an‐
1067 other complication is to be sure that the tracee is not already ptrace-
1068 stopped, because no signal delivery happens while it is—not even
1069 SIGSTOP.
1070 If the tracer dies, all tracees are automatically detached and
1072 restarted, unless they were in group-stop. Handling of restart from
1073 group-stop is currently buggy, but the "as planned" behavior is to
1074 leave tracee stopped and waiting for SIGCONT. If the tracee is
1075 restarted from signal-delivery-stop, the pending signal is injected.
1076 execve(2) under ptrace
1078 When one thread in a multithreaded process calls execve(2), the kernel
1079 destroys all other threads in the process, and resets the thread ID of
1080 the execing thread to the thread group ID (process ID). (Or, to put
1081 things another way, when a multithreaded process does an execve(2), at
1082 completion of the call, it appears as though the execve(2) occurred in
1083 the thread group leader, regardless of which thread did the execve(2).)
1084 This resetting of the thread ID looks very confusing to tracers:
1085 * All other threads stop in PTRACE_EVENT_EXIT stop, if the
1087 PTRACE_O_TRACEEXIT option was turned on. Then all other threads ex‐
1088 cept the thread group leader report death as if they exited via
1089 _exit(2) with exit code 0.
1090 * The execing tracee changes its thread ID while it is in the ex‐
1092 ecve(2). (Remember, under ptrace, the "pid" returned from wait‐
1093 pid(2), or fed into ptrace calls, is the tracee's thread ID.) That
1094 is, the tracee's thread ID is reset to be the same as its process
1095 ID, which is the same as the thread group leader's thread ID.
1096 * Then a PTRACE_EVENT_EXEC stop happens, if the PTRACE_O_TRACEEXEC op‐
1098 tion was turned on.
1099 * If the thread group leader has reported its PTRACE_EVENT_EXIT stop
1101 by this time, it appears to the tracer that the dead thread leader
1102 "reappears from nowhere". (Note: the thread group leader does not
1103 report death via WIFEXITED(status) until there is at least one other
1104 live thread. This eliminates the possibility that the tracer will
1105 see it dying and then reappearing.) If the thread group leader was
1106 still alive, for the tracer this may look as if thread group leader
1107 returns from a different system call than it entered, or even "re‐
1108 turned from a system call even though it was not in any system
1109 call". If the thread group leader was not traced (or was traced by
1110 a different tracer), then during execve(2) it will appear as if it
1111 has become a tracee of the tracer of the execing tracee.
1112 All of the above effects are the artifacts of the thread ID change in
1114 the tracee.
1115 The PTRACE_O_TRACEEXEC option is the recommended tool for dealing with
1117 this situation. First, it enables PTRACE_EVENT_EXEC stop, which occurs
1118 before execve(2) returns. In this stop, the tracer can use
1119 PTRACE_GETEVENTMSG to retrieve the tracee's former thread ID. (This
1120 feature was introduced in Linux 3.0.) Second, the PTRACE_O_TRACEEXEC
1121 option disables legacy SIGTRAP generation on execve(2).
1122 When the tracer receives PTRACE_EVENT_EXEC stop notification, it is
1124 guaranteed that except this tracee and the thread group leader, no
1125 other threads from the process are alive.
1126 On receiving the PTRACE_EVENT_EXEC stop notification, the tracer should
1128 clean up all its internal data structures describing the threads of
1129 this process, and retain only one data structure—one which describes
1130 the single still running tracee, with
1131 thread ID == thread group ID == process ID.
1133 Example: two threads call execve(2) at the same time:
1135 *** we get syscall-enter-stop in thread 1: **
1137 PID1 execve("/bin/foo", "foo" <unfinished ...>
1138 *** we issue PTRACE_SYSCALL for thread 1 **
1139 *** we get syscall-enter-stop in thread 2: **
1140 PID2 execve("/bin/bar", "bar" <unfinished ...>
1141 *** we issue PTRACE_SYSCALL for thread 2 **
1142 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
1143 *** we get syscall-exit-stop for PID0: **
1144 PID0 <... execve resumed> ) = 0
1145 If the PTRACE_O_TRACEEXEC option is not in effect for the execing
1147 tracee, and if the tracee was PTRACE_ATTACHed rather that
1148 PTRACE_SEIZEd, the kernel delivers an extra SIGTRAP to the tracee after
1149 execve(2) returns. This is an ordinary signal (similar to one which
1150 can be generated by kill -TRAP), not a special kind of ptrace-stop.
1151 Employing PTRACE_GETSIGINFO for this signal returns si_code set to 0
1152 (SI_USER). This signal may be blocked by signal mask, and thus may be
1153 delivered (much) later.
1154 Usually, the tracer (for example, strace(1)) would not want to show
1156 this extra post-execve SIGTRAP signal to the user, and would suppress
1157 its delivery to the tracee (if SIGTRAP is set to SIG_DFL, it is a
1158 killing signal). However, determining which SIGTRAP to suppress is not
1159 easy. Setting the PTRACE_O_TRACEEXEC option or using PTRACE_SEIZE and
1160 thus suppressing this extra SIGTRAP is the recommended approach.
1161 Real parent
1163 The ptrace API (ab)uses the standard UNIX parent/child signaling over
1164 waitpid(2). This used to cause the real parent of the process to stop
1165 receiving several kinds of waitpid(2) notifications when the child
1166 process is traced by some other process.
1167 Many of these bugs have been fixed, but as of Linux 2.6.38 several
1169 still exist; see BUGS below.
1170 As of Linux 2.6.38, the following is believed to work correctly:
1172 * exit/death by signal is reported first to the tracer, then, when the
1174 tracer consumes the waitpid(2) result, to the real parent (to the
1175 real parent only when the whole multithreaded process exits). If
1176 the tracer and the real parent are the same process, the report is
1177 sent only once.
1178
1180 On success, the PTRACE_PEEK* requests return the requested data (but
1181 see NOTES), the PTRACE_SECCOMP_GET_FILTER request returns the number of
1182 instructions in the BPF program, the PTRACE_GET_SYSCALL_INFO request
1183 returns the number of bytes available to be written by the kernel, and
1184 other requests return zero.
1185 On error, all requests return -1, and errno is set to indicate the er‐
1187 ror. Since the value returned by a successful PTRACE_PEEK* request may
1188 be -1, the caller must clear errno before the call, and then check it
1189 afterward to determine whether or not an error occurred.
1190
1192 EBUSY (i386 only) There was an error with allocating or freeing a de‐
1193 bug register.
1194 EFAULT There was an attempt to read from or write to an invalid area in
1196 the tracer's or the tracee's memory, probably because the area
1197 wasn't mapped or accessible. Unfortunately, under Linux, dif‐
1198 ferent variations of this fault will return EIO or EFAULT more
1199 or less arbitrarily.
1200 EINVAL An attempt was made to set an invalid option.
1202 EIO request is invalid, or an attempt was made to read from or write
1204 to an invalid area in the tracer's or the tracee's memory, or
1205 there was a word-alignment violation, or an invalid signal was
1206 specified during a restart request.
1207 EPERM The specified process cannot be traced. This could be because
1209 the tracer has insufficient privileges (the required capability
1210 is CAP_SYS_PTRACE); unprivileged processes cannot trace pro‐
1211 cesses that they cannot send signals to or those running set-
1212 user-ID/set-group-ID programs, for obvious reasons. Alterna‐
1213 tively, the process may already be being traced, or (on kernels
1214 before 2.6.26) be init(1) (PID 1).
1215 ESRCH The specified process does not exist, or is not currently being
1217 traced by the caller, or is not stopped (for requests that re‐
1218 quire a stopped tracee).
1219
1221 SVr4, 4.3BSD.
1222
1224 Although arguments to ptrace() are interpreted according to the proto‐
1225 type given, glibc currently declares ptrace() as a variadic function
1226 with only the request argument fixed. It is recommended to always sup‐
1227 ply four arguments, even if the requested operation does not use them,
1228 setting unused/ignored arguments to 0L or (void *) 0.
1229 In Linux kernels before 2.6.26, init(1), the process with PID 1, may
1231 not be traced.
1232 A tracees parent continues to be the tracer even if that tracer calls
1234 execve(2).
1235 The layout of the contents of memory and the USER area are quite oper‐
1237 ating-system- and architecture-specific. The offset supplied, and the
1238 data returned, might not entirely match with the definition of struct
1239 user.
1240 The size of a "word" is determined by the operating-system variant
1242 (e.g., for 32-bit Linux it is 32 bits).
1243 This page documents the way the ptrace() call works currently in Linux.
1245 Its behavior differs significantly on other flavors of UNIX. In any
1246 case, use of ptrace() is highly specific to the operating system and
1247 architecture.
1248 Ptrace access mode checking
1250 Various parts of the kernel-user-space API (not just ptrace() opera‐
1251 tions), require so-called "ptrace access mode" checks, whose outcome
1252 determines whether an operation is permitted (or, in a few cases,
1253 causes a "read" operation to return sanitized data). These checks are
1254 performed in cases where one process can inspect sensitive information
1255 about, or in some cases modify the state of, another process. The
1256 checks are based on factors such as the credentials and capabilities of
1257 the two processes, whether or not the "target" process is dumpable, and
1258 the results of checks performed by any enabled Linux Security Module
1259 (LSM)—for example, SELinux, Yama, or Smack—and by the commoncap LSM
1260 (which is always invoked).
1261 Prior to Linux 2.6.27, all access checks were of a single type. Since
1263 Linux 2.6.27, two access mode levels are distinguished:
1264 PTRACE_MODE_READ
1266 For "read" operations or other operations that are less danger‐
1267 ous, such as: get_robust_list(2); kcmp(2); reading
1268 /proc/[pid]/auxv, /proc/[pid]/environ, or /proc/[pid]/stat; or
1269 readlink(2) of a /proc/[pid]/ns/* file.
1270 PTRACE_MODE_ATTACH
1272 For "write" operations, or other operations that are more dan‐
1273 gerous, such as: ptrace attaching (PTRACE_ATTACH) to another
1274 process or calling process_vm_writev(2). (PTRACE_MODE_ATTACH
1275 was effectively the default before Linux 2.6.27.)
1276 Since Linux 4.5, the above access mode checks are combined (ORed) with
1278 one of the following modifiers:
1279 PTRACE_MODE_FSCREDS
1281 Use the caller's filesystem UID and GID (see credentials(7)) or
1282 effective capabilities for LSM checks.
1283 PTRACE_MODE_REALCREDS
1285 Use the caller's real UID and GID or permitted capabilities for
1286 LSM checks. This was effectively the default before Linux 4.5.
1287 Because combining one of the credential modifiers with one of the
1289 aforementioned access modes is typical, some macros are defined in the
1290 kernel sources for the combinations:
1291 PTRACE_MODE_READ_FSCREDS
1293 Defined as PTRACE_MODE_READ | PTRACE_MODE_FSCREDS.
1294 PTRACE_MODE_READ_REALCREDS
1296 Defined as PTRACE_MODE_READ | PTRACE_MODE_REALCREDS.
1297 PTRACE_MODE_ATTACH_FSCREDS
1299 Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS.
1300 PTRACE_MODE_ATTACH_REALCREDS
1302 Defined as PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS.
1303 One further modifier can be ORed with the access mode:
1305 PTRACE_MODE_NOAUDIT (since Linux 3.3)
1307 Don't audit this access mode check. This modifier is employed
1308 for ptrace access mode checks (such as checks when reading
1309 /proc/[pid]/stat) that merely cause the output to be filtered or
1310 sanitized, rather than causing an error to be returned to the
1311 caller. In these cases, accessing the file is not a security
1312 violation and there is no reason to generate a security audit
1313 record. This modifier suppresses the generation of such an au‐
1314 dit record for the particular access check.
1315 Note that all of the PTRACE_MODE_* constants described in this subsec‐
1317 tion are kernel-internal, and not visible to user space. The constant
1318 names are mentioned here in order to label the various kinds of ptrace
1319 access mode checks that are performed for various system calls and ac‐
1320 cesses to various pseudofiles (e.g., under /proc). These names are
1321 used in other manual pages to provide a simple shorthand for labeling
1322 the different kernel checks.
1323 The algorithm employed for ptrace access mode checking determines
1325 whether the calling process is allowed to perform the corresponding ac‐
1326 tion on the target process. (In the case of opening /proc/[pid] files,
1327 the "calling process" is the one opening the file, and the process with
1328 the corresponding PID is the "target process".) The algorithm is as
1329 follows:
1330 1. If the calling thread and the target thread are in the same thread
1332 group, access is always allowed.
1333 2. If the access mode specifies PTRACE_MODE_FSCREDS, then, for the
1335 check in the next step, employ the caller's filesystem UID and GID.
1336 (As noted in credentials(7), the filesystem UID and GID almost al‐
1337 ways have the same values as the corresponding effective IDs.)
1338 Otherwise, the access mode specifies PTRACE_MODE_REALCREDS, so use
1340 the caller's real UID and GID for the checks in the next step.
1341 (Most APIs that check the caller's UID and GID use the effective
1342 IDs. For historical reasons, the PTRACE_MODE_REALCREDS check uses
1343 the real IDs instead.)
1344 3. Deny access if neither of the following is true:
1346 • The real, effective, and saved-set user IDs of the target match
1348 the caller's user ID, and the real, effective, and saved-set group
1349 IDs of the target match the caller's group ID.
1350 • The caller has the CAP_SYS_PTRACE capability in the user namespace
1352 of the target.
1353 4. Deny access if the target process "dumpable" attribute has a value
1355 other than 1 (SUID_DUMP_USER; see the discussion of PR_SET_DUMPABLE
1356 in prctl(2)), and the caller does not have the CAP_SYS_PTRACE capa‐
1357 bility in the user namespace of the target process.
1358 5. The kernel LSM security_ptrace_access_check() interface is invoked
1360 to see if ptrace access is permitted. The results depend on the
1361 LSM(s). The implementation of this interface in the commoncap LSM
1362 performs the following steps:
1363 a) If the access mode includes PTRACE_MODE_FSCREDS, then use the
1365 caller's effective capability set in the following check; other‐
1366 wise (the access mode specifies PTRACE_MODE_REALCREDS, so) use
1367 the caller's permitted capability set.
1368 b) Deny access if neither of the following is true:
1370 • The caller and the target process are in the same user name‐
1372 space, and the caller's capabilities are a superset of the tar‐
1373 get process's permitted capabilities.
1374 • The caller has the CAP_SYS_PTRACE capability in the target
1376 process's user namespace.
1377 Note that the commoncap LSM does not distinguish between
1379 PTRACE_MODE_READ and PTRACE_MODE_ATTACH.
1380 6. If access has not been denied by any of the preceding steps, then
1382 access is allowed.
1383 /proc/sys/kernel/yama/ptrace_scope
1385 On systems with the Yama Linux Security Module (LSM) installed (i.e.,
1386 the kernel was configured with CONFIG_SECURITY_YAMA), the
1387 /proc/sys/kernel/yama/ptrace_scope file (available since Linux 3.4) can
1388 be used to restrict the ability to trace a process with ptrace() (and
1389 thus also the ability to use tools such as strace(1) and gdb(1)). The
1390 goal of such restrictions is to prevent attack escalation whereby a
1391 compromised process can ptrace-attach to other sensitive processes
1392 (e.g., a GPG agent or an SSH session) owned by the user in order to
1393 gain additional credentials that may exist in memory and thus expand
1394 the scope of the attack.
1395 More precisely, the Yama LSM limits two types of operations:
1397 * Any operation that performs a ptrace access mode PTRACE_MODE_ATTACH
1399 check—for example, ptrace() PTRACE_ATTACH. (See the "Ptrace access
1400 mode checking" discussion above.)
1401 * ptrace() PTRACE_TRACEME.
1403 A process that has the CAP_SYS_PTRACE capability can update the
1405 /proc/sys/kernel/yama/ptrace_scope file with one of the following val‐
1406 ues:
1407 0 ("classic ptrace permissions")
1409 No additional restrictions on operations that perform
1410 PTRACE_MODE_ATTACH checks (beyond those imposed by the commoncap
1411 and other LSMs).
1412 The use of PTRACE_TRACEME is unchanged.
1414 1 ("restricted ptrace") [default value]
1416 When performing an operation that requires a PTRACE_MODE_ATTACH
1417 check, the calling process must either have the CAP_SYS_PTRACE
1418 capability in the user namespace of the target process or it
1419 must have a predefined relationship with the target process. By
1420 default, the predefined relationship is that the target process
1421 must be a descendant of the caller.
1422 A target process can employ the prctl(2) PR_SET_PTRACER opera‐
1424 tion to declare an additional PID that is allowed to perform
1425 PTRACE_MODE_ATTACH operations on the target. See the kernel
1426 source file Documentation/admin-guide/LSM/Yama.rst (or Documen‐
1427 tation/security/Yama.txt before Linux 4.13) for further details.
1428 The use of PTRACE_TRACEME is unchanged.
1430 2 ("admin-only attach")
1432 Only processes with the CAP_SYS_PTRACE capability in the user
1433 namespace of the target process may perform PTRACE_MODE_ATTACH
1434 operations or trace children that employ PTRACE_TRACEME.
1435 3 ("no attach")
1437 No process may perform PTRACE_MODE_ATTACH operations or trace
1438 children that employ PTRACE_TRACEME.
1439 Once this value has been written to the file, it cannot be
1441 changed.
1442 With respect to values 1 and 2, note that creating a new user namespace
1444 effectively removes the protection offered by Yama. This is because a
1445 process in the parent user namespace whose effective UID matches the
1446 UID of the creator of a child namespace has all capabilities (including
1447 CAP_SYS_PTRACE) when performing operations within the child user name‐
1448 space (and further-removed descendants of that namespace). Conse‐
1449 quently, when a process tries to use user namespaces to sandbox itself,
1450 it inadvertently weakens the protections offered by the Yama LSM.
1451 C library/kernel differences
1453 At the system call level, the PTRACE_PEEKTEXT, PTRACE_PEEKDATA, and
1454 PTRACE_PEEKUSER requests have a different API: they store the result at
1455 the address specified by the data parameter, and the return value is
1456 the error flag. The glibc wrapper function provides the API given in
1457 DESCRIPTION above, with the result being returned via the function re‐
1458 turn value.
1459
1461 On hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared with a
1462 different value than the one for 2.4. This leads to applications com‐
1463 piled with 2.6 kernel headers failing when run on 2.4 kernels. This
1464 can be worked around by redefining PTRACE_SETOPTIONS to PTRACE_OLDSE‐
1465 TOPTIONS, if that is defined.
1466 Group-stop notifications are sent to the tracer, but not to real par‐
1468 ent. Last confirmed on 2.6.38.6.
1469 If a thread group leader is traced and exits by calling _exit(2), a
1471 PTRACE_EVENT_EXIT stop will happen for it (if requested), but the sub‐
1472 sequent WIFEXITED notification will not be delivered until all other
1473 threads exit. As explained above, if one of other threads calls ex‐
1474 ecve(2), the death of the thread group leader will never be reported.
1475 If the execed thread is not traced by this tracer, the tracer will
1476 never know that execve(2) happened. One possible workaround is to
1477 PTRACE_DETACH the thread group leader instead of restarting it in this
1478 case. Last confirmed on 2.6.38.6.
1479 A SIGKILL signal may still cause a PTRACE_EVENT_EXIT stop before actual
1481 signal death. This may be changed in the future; SIGKILL is meant to
1482 always immediately kill tasks even under ptrace. Last confirmed on
1483 Linux 3.13.
1484 Some system calls return with EINTR if a signal was sent to a tracee,
1486 but delivery was suppressed by the tracer. (This is very typical oper‐
1487 ation: it is usually done by debuggers on every attach, in order to not
1488 introduce a bogus SIGSTOP). As of Linux 3.2.9, the following system
1489 calls are affected (this list is likely incomplete): epoll_wait(2), and
1490 read(2) from an inotify(7) file descriptor. The usual symptom of this
1491 bug is that when you attach to a quiescent process with the command
1492 strace -p <process-ID>
1494 then, instead of the usual and expected one-line output such as
1496 restart_syscall(<... resuming interrupted call ...>_
1498 or
1500 select(6, [5], NULL, [5], NULL_
1502 ('_' denotes the cursor position), you observe more than one line. For
1504 example:
1505 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
1507 epoll_wait(4,_
1508 What is not visible here is that the process was blocked in
1510 epoll_wait(2) before strace(1) has attached to it. Attaching caused
1511 epoll_wait(2) to return to user space with the error EINTR. In this
1512 particular case, the program reacted to EINTR by checking the current
1513 time, and then executing epoll_wait(2) again. (Programs which do not
1514 expect such "stray" EINTR errors may behave in an unintended way upon
1515 an strace(1) attach.)
1516 Contrary to the normal rules, the glibc wrapper for ptrace() can set
1518 errno to zero.
1519
1521 gdb(1), ltrace(1), strace(1), clone(2), execve(2), fork(2), gettid(2),
1522 prctl(2), seccomp(2), sigaction(2), tgkill(2), vfork(2), waitpid(2),
1523 exec(3), capabilities(7), signal(7)
1524
1526 This page is part of release 5.13 of the Linux man-pages project. A
1527 description of the project, information about reporting bugs, and the
1528 latest version of this page, can be found at
1529 https://www.kernel.org/doc/man-pages/.
1530Linux 2021-03-22 PTRACE(2)