Debian Codegraph @

upstream/debian-unstable/man2/ptrace.2

raw
1 .\" Copyright 1999, ike Coleman <[email protected]>
2 .\" Copyright 2011, Denys Vlasenko <[email protected]>
3 .\" Copyright 2015-2016, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .\"
8 .\" FIXME The following are undocumented:
9 .\"
10 .\" PTRACE_GETWMMXREGS
11 .\" PTRACE_SETWMMXREGS
12 .\" ARM
13 .\" Linux 2.6.12
14 .\"
15 .\" PTRACE_SET_SYSCALL
16 .\" ARM and ARM64
17 .\" Linux 2.6.16
18 .\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f
19 .\" Author: Nicolas Pitre <[email protected]>
20 .\" Date: Sat Jan 14 19:30:04 2006 +0000
21 .\"
22 .\" PTRACE_GETCRUNCHREGS
23 .\" PTRACE_SETCRUNCHREGS
24 .\" ARM
25 .\" Linux 2.6.18
26 .\" commit 3bec6ded282b331552587267d67a06ed7fd95ddd
27 .\" Author: Lennert Buytenhek <[email protected]>
28 .\" Date: Tue Jun 27 22:56:18 2006 +0100
29 .\"
30 .\" PTRACE_GETVFPREGS
31 .\" PTRACE_SETVFPREGS
32 .\" ARM and ARM64
33 .\" Linux 2.6.30
34 .\" commit 3d1228ead618b88e8606015cbabc49019981805d
35 .\" Author: Catalin Marinas <[email protected]>
36 .\" Date: Wed Feb 11 13:12:56 2009 +0100
37 .\"
38 .\" PTRACE_GETHBPREGS
39 .\" PTRACE_SETHBPREGS
40 .\" ARM and ARM64
41 .\" Linux 2.6.37
42 .\" commit 864232fa1a2f8dfe003438ef0851a56722740f3e
43 .\" Author: Will Deacon <[email protected]>
44 .\" Date: Fri Sep 3 10:42:55 2010 +0100
45 .\"
46 .\" PTRACE_SINGLEBLOCK
47 .\" Since at least Linux 2.4.0 on various architectures
48 .\" Since Linux 2.6.25 on x86 (and others?)
49 .\" commit 5b88abbf770a0e1975c668743100f42934f385e8
50 .\" Author: Roland McGrath <[email protected]>
51 .\" Date: Wed Jan 30 13:30:53 2008 +0100
52 .\" ptrace: generic PTRACE_SINGLEBLOCK
53 .\"
54 .\" PTRACE_GETFPXREGS
55 .\" PTRACE_SETFPXREGS
56 .\" Since at least Linux 2.4.0 on various architectures
57 .\"
58 .\" PTRACE_GETFDPIC
59 .\" PTRACE_GETFDPIC_EXEC
60 .\" PTRACE_GETFDPIC_INTERP
61 .\" blackfin, c6x, frv, sh
62 .\" First appearance in Linux 2.6.11 on frv
63 .\"
64 .\" and others that can be found in the arch/*/include/uapi/asm/ptrace files
65 .\"
66 .TH ptrace 2 2026-02-10 "Linux man-pages 6.18"
67 .SH NAME
68 ptrace \- process trace
69 .SH LIBRARY
70 Standard C library
71 .RI ( libc ,\~ \-lc )
72 .SH SYNOPSIS
73 .nf
74 .B #include <sys/ptrace.h>
75 .P
76 .BI "long ptrace(enum __ptrace_request " op ", pid_t " pid ,
77 .BI " void *" addr ", void *" data );
78 .fi
79 .SH DESCRIPTION
80 The
81 .BR ptrace ()
82 system call provides a means by which one process (the "tracer")
83 may observe and control the execution of another process (the "tracee"),
84 and examine and change the tracee's memory and registers.
85 It is primarily used to implement breakpoint debugging and system
86 call tracing.
87 .P
88 A tracee first needs to be attached to the tracer.
89 Attachment and subsequent commands are per thread:
90 in a multithreaded process,
91 every thread can be individually attached to a
92 (potentially different) tracer,
93 or left not attached and thus not debugged.
94 Therefore, "tracee" always means "(one) thread",
95 never "a (possibly multithreaded) process".
96 Ptrace commands are always sent to
97 a specific tracee using a call of the form
98 .P
99 .in +4n
100 .EX
101 ptrace(PTRACE_foo, pid, ...)
102 .EE
103 .in
104 .P
105 where
106 .I pid
107 is the thread ID of the corresponding Linux thread.
108 .P
109 (Note that in this page, a "multithreaded process"
110 means a thread group consisting of threads created using the
111 .BR clone (2)
112 .B CLONE_THREAD
113 flag.)
114 .P
115 A process can initiate a trace by calling
116 .BR fork (2)
117 and having the resulting child do a
118 .BR PTRACE_TRACEME ,
119 followed (typically) by an
120 .BR execve (2).
121 Alternatively, one process may commence tracing another process using
122 .B PTRACE_ATTACH
123 or
124 .BR PTRACE_SEIZE .
125 .P
126 While being traced, the tracee will stop each time a signal is delivered,
127 even if the signal is being ignored.
128 (An exception is
129 .BR SIGKILL ,
130 which has its usual effect.)
131 The tracer will be notified at its next call to
132 .BR waitpid (2)
133 (or one of the related "wait" system calls);
134 that call will return a
135 .I status
136 value containing information that indicates
137 the cause of the stop in the tracee.
138 While the tracee is stopped,
139 the tracer can use various ptrace operations to inspect and modify the tracee.
140 The tracer then causes the tracee to continue,
141 optionally ignoring the delivered signal
142 (or even delivering a different signal instead).
143 .P
144 If the
145 .B PTRACE_O_TRACEEXEC
146 option is not in effect, all successful calls to
147 .BR execve (2)
148 by the traced process will cause it to be sent a
149 .B SIGTRAP
150 signal,
151 giving the parent a chance to gain control before the new program
152 begins execution.
153 .P
154 When the tracer is finished tracing, it can cause the tracee to continue
155 executing in a normal, untraced mode via
156 .BR PTRACE_DETACH .
157 .P
158 The value of
159 .I op
160 determines the operation to be performed:
161 .TP
162 .B PTRACE_TRACEME
163 Indicate that this process is to be traced by its parent.
164 A process probably shouldn't make this operation if its parent
165 isn't expecting to trace it.
166 .RI ( pid ,
167 .IR addr ,
168 and
169 .I data
170 are ignored.)
171 .IP
172 The
173 .B PTRACE_TRACEME
174 operation is used only by the tracee;
175 the remaining operations are used only by the tracer.
176 In the following operations,
177 .I pid
178 specifies the thread ID of the tracee to be acted on.
179 For operations other than
180 .BR PTRACE_ATTACH ,
181 .BR PTRACE_SEIZE ,
182 .BR PTRACE_INTERRUPT ,
183 and
184 .BR PTRACE_KILL ,
185 the tracee must be stopped.
186 .TP
187 .B PTRACE_PEEKTEXT
188 .TQ
189 .B PTRACE_PEEKDATA
190 Read a word at the address
191 .I addr
192 in the tracee's memory, returning the word as the result of the
193 .BR ptrace ()
194 call.
195 Linux does not have separate text and data address spaces,
196 so these two operations are currently equivalent.
197 .RI ( data
198 is ignored;
199 but see NOTES.)
200 .TP
201 .B PTRACE_PEEKUSER
202 .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
203 .\" and that is the name that seems common on other systems.
204 Read a word at offset
205 .I addr
206 in the tracee's USER area,
207 which holds the registers and other information about the process
208 (see
209 .IR <sys/user.h> ).
210 The word is returned as the result of the
211 .BR ptrace ()
212 call.
213 Typically, the offset must be word-aligned, though this might vary by
214 architecture.
215 See NOTES.
216 .RI ( data
217 is ignored;
218 but see NOTES.)
219 .TP
220 .B PTRACE_POKETEXT
221 .TQ
222 .B PTRACE_POKEDATA
223 Copy the word
224 .I data
225 to the address
226 .I addr
227 in the tracee's memory.
228 As for
229 .B PTRACE_PEEKTEXT
230 and
231 .BR PTRACE_PEEKDATA ,
232 these two operations are currently equivalent.
233 .TP
234 .B PTRACE_POKEUSER
235 .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
236 .\" and that is the name that seems common on other systems.
237 Copy the word
238 .I data
239 to offset
240 .I addr
241 in the tracee's USER area.
242 As for
243 .BR PTRACE_PEEKUSER ,
244 the offset must typically be word-aligned.
245 In order to maintain the integrity of the kernel,
246 some modifications to the USER area are disallowed.
247 .\" FIXME In the preceding sentence, which modifications are disallowed,
248 .\" and when they are disallowed, how does user space discover that fact?
249 .TP
250 .B PTRACE_GETREGS
251 .TQ
252 .B PTRACE_GETFPREGS
253 Copy the tracee's general-purpose or floating-point registers,
254 respectively, to the address
255 .I data
256 in the tracer.
257 See
258 .I <sys/user.h>
259 for information on the format of this data.
260 .RI ( addr
261 is ignored.)
262 Note that SPARC systems have the meaning of
263 .I data
264 and
265 .I addr
266 reversed;
267 that is,
268 .I data
269 is ignored and the registers are copied to the address
270 .IR addr .
271 .B PTRACE_GETREGS
272 and
273 .B PTRACE_GETFPREGS
274 are not present on all architectures.
275 .TP
276 .BR PTRACE_GETREGSET " (since Linux 2.6.34)"
277 Read the tracee's registers.
278 .I addr
279 specifies, in an architecture-dependent way, the type of registers to be read.
280 .B NT_PRSTATUS
281 (with numerical value 1)
282 usually results in reading of general-purpose registers.
283 If the CPU has, for example,
284 floating-point and/or vector registers, they can be retrieved by setting
285 .I addr
286 to the corresponding
287 .B NT_foo
288 constant.
289 .I data
290 points to a
291 .BR "struct iovec" ,
292 which describes the destination buffer's location and size.
293 On return, the kernel modifies
294 .B iov.len
295 to indicate the actual number of bytes returned.
296 .TP
297 .B PTRACE_SETREGS
298 .TQ
299 .B PTRACE_SETFPREGS
300 Modify the tracee's general-purpose or floating-point registers,
301 respectively, from the address
302 .I data
303 in the tracer.
304 As for
305 .BR PTRACE_POKEUSER ,
306 some general-purpose register modifications may be disallowed.
307 .\" FIXME . In the preceding sentence, which modifications are disallowed,
308 .\" and when they are disallowed, how does user space discover that fact?
309 .RI ( addr
310 is ignored.)
311 Note that SPARC systems have the meaning of
312 .I data
313 and
314 .I addr
315 reversed;
316 that is,
317 .I data
318 is ignored
319 and the registers are copied from the address
320 .IR addr .
321 .B PTRACE_SETREGS
322 and
323 .B PTRACE_SETFPREGS
324 are not present on all architectures.
325 .TP
326 .BR PTRACE_SETREGSET " (since Linux 2.6.34)"
327 Modify the tracee's registers.
328 The meaning of
329 .I addr
330 and
331 .I data
332 is analogous to
333 .BR PTRACE_GETREGSET .
334 .TP
335 .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
336 Retrieve information about the signal that caused the stop.
337 Copy a
338 .I siginfo_t
339 structure (see
340 .BR sigaction (2))
341 from the tracee to the address
342 .I data
343 in the tracer.
344 .RI ( addr
345 is ignored.)
346 .TP
347 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
348 Set signal information:
349 copy a
350 .I siginfo_t
351 structure from the address
352 .I data
353 in the tracer to the tracee.
354 This will affect only signals that would normally be delivered to
355 the tracee and were caught by the tracer.
356 It may be difficult to tell
357 these normal signals from synthetic signals generated by
358 .BR ptrace ()
359 itself.
360 .RI ( addr
361 is ignored.)
362 .TP
363 .BR PTRACE_PEEKSIGINFO " (since Linux 3.10)"
364 .\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4
365 Retrieve
366 .I siginfo_t
367 structures without removing signals from a queue.
368 .I addr
369 points to a
370 .I ptrace_peeksiginfo_args
371 structure that specifies the ordinal position from which
372 copying of signals should start,
373 and the number of signals to copy.
374 .I siginfo_t
375 structures are copied into the buffer pointed to by
376 .IR data .
377 The return value contains the number of copied signals (zero indicates
378 that there is no signal corresponding to the specified ordinal position).
379 Within the returned
380 .I siginfo
381 structures,
382 the
383 .I si_code
384 field includes information
385 .RB ( __SI_CHLD ,
386 .BR __SI_FAULT ,
387 etc.) that are not otherwise exposed to user space.
388 .P
389 .in +4n
390 .EX
391 struct ptrace_peeksiginfo_args {
392 u64 off; /* Ordinal position in queue at which
393 to start copying signals */
394 u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */
395 s32 nr; /* Number of signals to copy */
396 };
397 .EE
398 .in
399 .IP
400 Currently, there is only one flag,
401 .BR PTRACE_PEEKSIGINFO_SHARED ,
402 for dumping signals from the process-wide signal queue.
403 If this flag is not set,
404 signals are read from the per-thread queue of the specified thread.
405 .in
406 .TP
407 .BR PTRACE_GETSIGMASK " (since Linux 3.11)"
408 .\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
409 Place a copy of the mask of blocked signals (see
410 .BR sigprocmask (2))
411 in the buffer pointed to by
412 .IR data ,
413 which should be a pointer to a buffer of type
414 .IR sigset_t .
415 The
416 .I addr
417 argument contains the size of the buffer pointed to by
418 .I data
419 (i.e.,
420 .IR sizeof(sigset_t) ).
421 .TP
422 .BR PTRACE_SETSIGMASK " (since Linux 3.11)"
423 Change the mask of blocked signals (see
424 .BR sigprocmask (2))
425 to the value specified in the buffer pointed to by
426 .IR data ,
427 which should be a pointer to a buffer of type
428 .IR sigset_t .
429 The
430 .I addr
431 argument contains the size of the buffer pointed to by
432 .I data
433 (i.e.,
434 .IR sizeof(sigset_t) ).
435 .TP
436 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
437 Set ptrace options from
438 .IR data .
439 .RI ( addr
440 is ignored.)
441 .I data
442 is interpreted as a bit mask of options,
443 which are specified by the following flags:
444 .RS
445 .TP
446 .BR PTRACE_O_EXITKILL " (since Linux 3.8)"
447 .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123
448 Send a
449 .B SIGKILL
450 signal to the tracee if the tracer exits.
451 This option is useful for ptrace jailers that
452 want to ensure that tracees can never escape the tracer's control.
453 .TP
454 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
455 Stop the tracee at the next
456 .BR clone (2)
457 and automatically start tracing the newly cloned process,
458 which will start with a
459 .BR SIGSTOP ,
460 or
461 .B PTRACE_EVENT_STOP
462 if
463 .B PTRACE_SEIZE
464 was used.
465 A
466 .BR waitpid (2)
467 by the tracer will return a
468 .I status
469 value such that
470 .IP
471 .nf
472 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
473 .fi
474 .IP
475 The PID of the new process can be retrieved with
476 .BR PTRACE_GETEVENTMSG .
477 .IP
478 This option may not catch
479 .BR clone (2)
480 calls in all cases.
481 If the tracee calls
482 .BR clone (2)
483 with the
484 .B CLONE_VFORK
485 flag,
486 .B PTRACE_EVENT_VFORK
487 will be delivered instead
488 if
489 .B PTRACE_O_TRACEVFORK
490 is set;
491 otherwise if the tracee calls
492 .BR clone (2)
493 with the exit signal set to
494 .BR SIGCHLD ,
495 .B PTRACE_EVENT_FORK
496 will be delivered if
497 .B PTRACE_O_TRACEFORK
498 is set.
499 .TP
500 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
501 Stop the tracee at the next
502 .BR execve (2).
503 A
504 .BR waitpid (2)
505 by the tracer will return a
506 .I status
507 value such that
508 .IP
509 .nf
510 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
511 .fi
512 .IP
513 If the execing thread is not a thread group leader,
514 the thread ID is reset to thread group leader's ID before this stop.
515 Since Linux 3.0, the former thread ID can be retrieved with
516 .BR PTRACE_GETEVENTMSG .
517 .TP
518 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
519 Stop the tracee at exit.
520 A
521 .BR waitpid (2)
522 by the tracer will return a
523 .I status
524 value such that
525 .IP
526 .nf
527 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
528 .fi
529 .IP
530 The tracee's exit status can be retrieved with
531 .BR PTRACE_GETEVENTMSG .
532 .IP
533 The tracee is stopped early during process exit,
534 when registers are still available,
535 allowing the tracer to see where the exit occurred,
536 whereas the normal exit notification is done after the process
537 is finished exiting.
538 Even though context is available,
539 the tracer cannot prevent the exit from happening at this point.
540 .TP
541 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
542 Stop the tracee at the next
543 .BR fork (2)
544 and automatically start tracing the newly forked process,
545 which will start with a
546 .BR SIGSTOP ,
547 or
548 .B PTRACE_EVENT_STOP
549 if
550 .B PTRACE_SEIZE
551 was used.
552 A
553 .BR waitpid (2)
554 by the tracer will return a
555 .I status
556 value such that
557 .IP
558 .nf
559 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
560 .fi
561 .IP
562 The PID of the new process can be retrieved with
563 .BR PTRACE_GETEVENTMSG .
564 .TP
565 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
566 When delivering system call traps, set bit 7 in the signal number
567 (i.e., deliver
568 .IR "SIGTRAP|0x80" ).
569 This makes it easy for the tracer to distinguish
570 normal traps from those caused by a system call.
571 .TP
572 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
573 Stop the tracee at the next
574 .BR vfork (2)
575 and automatically start tracing the newly vforked process,
576 which will start with a
577 .BR SIGSTOP ,
578 or
579 .B PTRACE_EVENT_STOP
580 if
581 .B PTRACE_SEIZE
582 was used.
583 A
584 .BR waitpid (2)
585 by the tracer will return a
586 .I status
587 value such that
588 .IP
589 .nf
590 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
591 .fi
592 .IP
593 The PID of the new process can be retrieved with
594 .BR PTRACE_GETEVENTMSG .
595 .TP
596 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
597 Stop the tracee at the completion of the next
598 .BR vfork (2).
599 A
600 .BR waitpid (2)
601 by the tracer will return a
602 .I status
603 value such that
604 .IP
605 .nf
606 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
607 .fi
608 .IP
609 The PID of the new process can (since Linux 2.6.18) be retrieved with
610 .BR PTRACE_GETEVENTMSG .
611 .TP
612 .BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)"
613 Stop the tracee when a
614 .BR seccomp (2)
615 .B SECCOMP_RET_TRACE
616 rule is triggered.
617 A
618 .BR waitpid (2)
619 by the tracer will return a
620 .I status
621 value such that
622 .IP
623 .nf
624 status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))
625 .fi
626 .IP
627 While this triggers a
628 .B PTRACE_EVENT
629 stop, it is similar to a syscall-enter-stop.
630 For details, see the note on
631 .B PTRACE_EVENT_SECCOMP
632 below.
633 The seccomp event message data (from the
634 .B SECCOMP_RET_DATA
635 portion of the seccomp filter rule) can be retrieved with
636 .BR PTRACE_GETEVENTMSG .
637 .TP
638 .BR PTRACE_O_SUSPEND_SECCOMP " (since Linux 4.3)"
639 .\" commit 13c4a90119d28cfcb6b5bdd820c233b86c2b0237
640 Suspend the tracee's seccomp protections.
641 This applies regardless of mode, and
642 can be used when the tracee has not yet installed seccomp filters.
643 That is, a valid use case is to suspend a tracee's seccomp protections
644 before they are installed by the tracee,
645 let the tracee install the filters,
646 and then clear this flag when the filters should be resumed.
647 Setting this option requires that the tracer have the
648 .B CAP_SYS_ADMIN
649 capability,
650 not have any seccomp protections installed, and not have
651 .B PTRACE_O_SUSPEND_SECCOMP
652 set on itself.
653 .RE
654 .TP
655 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
656 Retrieve a message (as an
657 .IR "unsigned long" )
658 about the ptrace event
659 that just happened, placing it at the address
660 .I data
661 in the tracer.
662 For
663 .BR PTRACE_EVENT_EXIT ,
664 this is the tracee's exit status.
665 For
666 .BR PTRACE_EVENT_FORK ,
667 .BR PTRACE_EVENT_VFORK ,
668 .BR PTRACE_EVENT_VFORK_DONE ,
669 and
670 .BR PTRACE_EVENT_CLONE ,
671 this is the PID of the new process.
672 For
673 .BR PTRACE_EVENT_SECCOMP ,
674 this is the
675 .BR seccomp (2)
676 filter's
677 .B SECCOMP_RET_DATA
678 associated with the triggered rule.
679 .RI ( addr
680 is ignored.)
681 .TP
682 .B PTRACE_CONT
683 Restart the stopped tracee process.
684 If
685 .I data
686 is nonzero,
687 it is interpreted as the number of a signal to be delivered to the tracee;
688 otherwise, no signal is delivered.
689 Thus, for example, the tracer can control
690 whether a signal sent to the tracee is delivered or not.
691 .RI ( addr
692 is ignored.)
693 .TP
694 .B PTRACE_SYSCALL
695 .TQ
696 .B PTRACE_SINGLESTEP
697 Restart the stopped tracee as for
698 .BR PTRACE_CONT ,
699 but arrange for the tracee to be stopped at
700 the next entry to or exit from a system call,
701 or after execution of a single instruction, respectively.
702 (The tracee will also, as usual, be stopped upon receipt of a signal.)
703 From the tracer's perspective, the tracee will appear to have been
704 stopped by receipt of a
705 .BR SIGTRAP .
706 So, for
707 .BR PTRACE_SYSCALL ,
708 for example, the idea is to inspect
709 the arguments to the system call at the first stop,
710 then do another
711 .B PTRACE_SYSCALL
712 and inspect the return value of the system call at the second stop.
713 The
714 .I data
715 argument is treated as for
716 .BR PTRACE_CONT .
717 .RI ( addr
718 is ignored.)
719 .TP
720 .BR PTRACE_SET_SYSCALL " (since Linux 2.6.16)"
721 .\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f
722 When in syscall-enter-stop,
723 change the number of the system call that is about to
724 be executed to the number specified in the
725 .I data
726 argument.
727 The
728 .I addr
729 argument is ignored.
730 This operation is currently
731 .\" As of 4.19-rc2
732 supported only on arm (and arm64, though only for backwards compatibility),
733 .\" commit 27aa55c5e5123fa8b8ad0156559d34d7edff58ca
734 but most other architectures have other means of accomplishing this
735 (usually by changing the register that the userland code passed the
736 system call number in).
737 .\" see change_syscall in tools/testing/selftests/seccomp/seccomp_bpf.c
738 .\" and also strace's linux/*/set_scno.c files.
739 .TP
740 .B PTRACE_SYSEMU
741 .TQ
742 .BR PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
743 For
744 .BR PTRACE_SYSEMU ,
745 continue and stop on entry to the next system call,
746 which will not be executed.
747 See the documentation on syscall-stops below.
748 For
749 .BR PTRACE_SYSEMU_SINGLESTEP ,
750 do the same but also singlestep if not a system call.
751 This call is used by programs like
752 User Mode Linux that want to emulate all the tracee's system calls.
753 The
754 .I data
755 argument is treated as for
756 .BR PTRACE_CONT .
757 The
758 .I addr
759 argument is ignored.
760 These operations are currently
761 .\" As at 3.7
762 supported only on x86.
763 .TP
764 .BR PTRACE_LISTEN " (since Linux 3.4)"
765 Restart the stopped tracee, but prevent it from executing.
766 The resulting state of the tracee is similar to a process which
767 has been stopped by a
768 .B SIGSTOP
769 (or other stopping signal).
770 See the "group-stop" subsection for additional information.
771 .B PTRACE_LISTEN
772 works only on tracees attached by
773 .BR PTRACE_SEIZE .
774 .TP
775 .B PTRACE_KILL
776 Send the tracee a
777 .B SIGKILL
778 to terminate it.
779 .RI ( addr
780 and
781 .I data
782 are ignored.)
783 .IP
784 .I This operation is deprecated; do not use it!
785 Instead, send a
786 .B SIGKILL
787 directly using
788 .BR kill (2)
789 or
790 .BR tgkill (2).
791 The problem with
792 .B PTRACE_KILL
793 is that it requires the tracee to be in signal-delivery-stop,
794 otherwise it may not work
795 (i.e., may complete successfully but won't kill the tracee).
796 By contrast, sending a
797 .B SIGKILL
798 directly has no such limitation.
799 .\" [Note from Denys Vlasenko:
800 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
801 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
802 .TP
803 .BR PTRACE_INTERRUPT " (since Linux 3.4)"
804 Stop a tracee.
805 If the tracee is running or sleeping in kernel space and
806 .B PTRACE_SYSCALL
807 is in effect,
808 the system call is interrupted and syscall-exit-stop is reported.
809 (The interrupted system call is restarted when the tracee is restarted.)
810 If the tracee was already stopped by a signal and
811 .B PTRACE_LISTEN
812 was sent to it,
813 the tracee stops with
814 .B PTRACE_EVENT_STOP
815 and
816 .I WSTOPSIG(status)
817 returns the stop signal.
818 If any other ptrace-stop is generated at the same time (for example,
819 if a signal is sent to the tracee), this ptrace-stop happens.
820 If none of the above applies (for example, if the tracee is running in user
821 space), it stops with
822 .B PTRACE_EVENT_STOP
823 with
824 .I WSTOPSIG(status)
825 ==
826 .BR SIGTRAP .
827 .B PTRACE_INTERRUPT
828 only works on tracees attached by
829 .BR PTRACE_SEIZE .
830 .TP
831 .B PTRACE_ATTACH
832 Attach to the process specified in
833 .IR pid ,
834 making it a tracee of the calling process.
835 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
836 .\" "I think it isn't true in non-ancient 2.4 and in Linux 2.6/3.x.
837 .\" Basically, it's not true for any Linux in practical use.
838 .\" the behavior of the tracee is as if it had done a
839 .\" .BR PTRACE_TRACEME .
840 .\" The calling process actually becomes the parent of the tracee
841 .\" process for most purposes (e.g., it will receive
842 .\" notification of tracee events and appears in
843 .\" .BR ps (1)
844 .\" output as the tracee's parent), but a
845 .\" .BR getppid (2)
846 .\" by the tracee will still return the PID of the original parent.
847 The tracee is sent a
848 .BR SIGSTOP ,
849 but will not necessarily have stopped
850 by the completion of this call;
851 use
852 .BR waitpid (2)
853 to wait for the tracee to stop.
854 See the "Attaching and detaching" subsection for additional information.
855 .RI ( addr
856 and
857 .I data
858 are ignored.)
859 .IP
860 Permission to perform a
861 .B PTRACE_ATTACH
862 is governed by a ptrace access mode
863 .B PTRACE_MODE_ATTACH_REALCREDS
864 check;
865 see below.
866 .TP
867 .BR PTRACE_SEIZE " (since Linux 3.4)"
868 .\"
869 .\" Noted by Dmitry Levin:
870 .\"
871 .\" PTRACE_SEIZE was introduced by commit v3.1-rc1~308^2~28, but
872 .\" it had to be used along with a temporary flag PTRACE_SEIZE_DEVEL,
873 .\" which was removed later by commit v3.4-rc1~109^2~20.
874 .\"
875 .\" That is, [before] v3.4 we had a test mode of PTRACE_SEIZE API,
876 .\" which was not compatible with the current PTRACE_SEIZE API introduced
877 .\" in Linux 3.4.
878 .\"
879 Attach to the process specified in
880 .IR pid ,
881 making it a tracee of the calling process.
882 Unlike
883 .BR PTRACE_ATTACH ,
884 .B PTRACE_SEIZE
885 does not stop the process.
886 Group-stops are reported as
887 .B PTRACE_EVENT_STOP
888 and
889 .I WSTOPSIG(status)
890 returns the stop signal.
891 Automatically attached children stop with
892 .B PTRACE_EVENT_STOP
893 and
894 .I WSTOPSIG(status)
895 returns
896 .B SIGTRAP
897 instead of having
898 .B SIGSTOP
899 signal delivered to them.
900 .BR execve (2)
901 does not deliver an extra
902 .BR SIGTRAP .
903 Only a
904 .BR PTRACE_SEIZE d
905 process can accept
906 .B PTRACE_INTERRUPT
907 and
908 .B PTRACE_LISTEN
909 commands.
910 The "seized" behavior just described is inherited by
911 children that are automatically attached using
912 .BR PTRACE_O_TRACEFORK ,
913 .BR PTRACE_O_TRACEVFORK ,
914 and
915 .BR PTRACE_O_TRACECLONE .
916 .I addr
917 must be zero.
918 .I data
919 contains a bit mask of ptrace options to activate immediately.
920 .IP
921 Permission to perform a
922 .B PTRACE_SEIZE
923 is governed by a ptrace access mode
924 .B PTRACE_MODE_ATTACH_REALCREDS
925 check;
926 see below.
927 .\"
928 .TP
929 .BR PTRACE_SECCOMP_GET_FILTER " (since Linux 4.4)"
930 .\" commit f8e529ed941ba2bbcbf310b575d968159ce7e895
931 This operation allows the tracer to dump the tracee's
932 classic BPF filters.
933 .IP
934 .I addr
935 is an integer specifying the index of the filter to be dumped.
936 The most recently installed filter has the index 0.
937 If
938 .I addr
939 is greater than the number of installed filters,
940 the operation fails with the error
941 .BR ENOENT .
942 .IP
943 .I data
944 is either a pointer to a
945 .I struct sock_filter
946 array that is large enough to store the BPF program,
947 or NULL if the program is not to be stored.
948 .IP
949 Upon success,
950 the return value is the number of instructions in the BPF program.
951 If
952 .I data
953 was NULL, then this return value can be used to correctly size the
954 .I struct sock_filter
955 array passed in a subsequent call.
956 .IP
957 This operation fails with the error
958 .B EACCES
959 if the caller does not have the
960 .B CAP_SYS_ADMIN
961 capability or if the caller is in strict or filter seccomp mode.
962 If the filter referred to by
963 .I addr
964 is not a classic BPF filter, the operation fails with the error
965 .BR EMEDIUMTYPE .
966 .IP
967 This operation is available if the kernel was configured with both the
968 .B CONFIG_SECCOMP_FILTER
969 and the
970 .B CONFIG_CHECKPOINT_RESTORE
971 options.
972 .TP
973 .B PTRACE_DETACH
974 Restart the stopped tracee as for
975 .BR PTRACE_CONT ,
976 but first detach from it.
977 Under Linux, a tracee can be detached in this way regardless
978 of which method was used to initiate tracing.
979 .RI ( addr
980 is ignored.)
981 .\"
982 .TP
983 .BR PTRACE_GET_THREAD_AREA " (since Linux 2.6.0)"
984 This operation performs a similar task to
985 .BR get_thread_area (2).
986 It reads the TLS entry in the GDT whose index is given in
987 .IR addr ,
988 placing a copy of the entry into the
989 .I struct user_desc
990 pointed to by
991 .IR data .
992 (By contrast with
993 .BR get_thread_area (2),
994 the
995 .I entry_number
996 of the
997 .I struct user_desc
998 is ignored.)
999 .TP
1000 .BR PTRACE_SET_THREAD_AREA " (since Linux 2.6.0)"
1001 This operation performs a similar task to
1002 .BR set_thread_area (2).
1003 It sets the TLS entry in the GDT whose index is given in
1004 .IR addr ,
1005 assigning it the data supplied in the
1006 .I struct user_desc
1007 pointed to by
1008 .IR data .
1009 (By contrast with
1010 .BR set_thread_area (2),
1011 the
1012 .I entry_number
1013 of the
1014 .I struct user_desc
1015 is ignored;
1016 in other words,
1017 this ptrace operation can't be used to allocate a free TLS entry.)
1018 .TP
1019 .BR PTRACE_GET_SYSCALL_INFO " (since Linux 5.3)"
1020 .\" commit 201766a20e30f982ccfe36bebfad9602c3ff574a
1021 Retrieve information about the system call that caused the stop.
1022 The information is placed into the buffer pointed by the
1023 .I data
1024 argument, which should be a pointer to a buffer of type
1025 .IR "struct ptrace_syscall_info" .
1026 The
1027 .I addr
1028 argument contains the size of the buffer pointed to
1029 by the
1030 .I data
1031 argument (i.e.,
1032 .IR "sizeof(struct ptrace_syscall_info)" ).
1033 The return value contains the number of bytes available
1034 to be written by the kernel.
1035 If the size of the data to be written by the kernel exceeds the size
1036 specified by the
1037 .I addr
1038 argument, the output data is truncated.
1039 .IP
1040 The
1041 .I ptrace_syscall_info
1042 structure contains the following fields:
1043 .IP
1044 .in +4n
1045 .EX
1046 struct ptrace_syscall_info {
1047 __u8 op; /* Type of system call stop */
1048 __u8 reserved; /* Reserved for future use, must be zero */
1049 __u16 flags; /* Reserved for future use, must be zero */
1050 __u32 arch; /* AUDIT_ARCH_* value; see seccomp(2) */
1051 __u64 instruction_pointer; /* CPU instruction pointer */
1052 __u64 stack_pointer; /* CPU stack pointer */
1053 union {
1054 struct { /* op == PTRACE_SYSCALL_INFO_ENTRY */
1055 __u64 nr; /* System call number */
1056 __u64 args[6]; /* System call arguments */
1057 } entry;
1058 struct { /* op == PTRACE_SYSCALL_INFO_EXIT */
1059 __s64 rval; /* System call return value */
1060 __u8 is_error; /* System call error flag;
1061 Boolean: does rval contain
1062 an error value (\-ERRCODE) or
1063 a nonerror return value? */
1064 } exit;
1065 struct { /* op == PTRACE_SYSCALL_INFO_SECCOMP */
1066 __u64 nr; /* System call number */
1067 __u64 args[6]; /* System call arguments */
1068 __u32 ret_data; /* SECCOMP_RET_DATA portion
1069 of SECCOMP_RET_TRACE
1070 return value */
1071 } seccomp;
1072 };
1073 };
1074 .EE
1075 .in
1076 .IP
1077 The
1078 .IR op ,
1079 .IR arch ,
1080 .IR instruction_pointer ,
1081 and
1082 .I stack_pointer
1083 fields are defined for all kinds of ptrace system call stops.
1084 The rest of the structure is a union;
1085 one should read only those fields
1086 that are meaningful for the kind of system call stop specified by the
1087 .I op
1088 field.
1089 .IP
1090 The
1091 .I op
1092 field has one of the following values (defined in
1093 .IR <linux/ptrace.h> )
1094 indicating what type of stop occurred and
1095 which part of the union is filled:
1096 .RS
1097 .TP
1098 .B PTRACE_SYSCALL_INFO_ENTRY
1099 The
1100 .I entry
1101 component of the union contains information relating to a
1102 system call entry stop.
1103 .TP
1104 .B PTRACE_SYSCALL_INFO_EXIT
1105 The
1106 .I exit
1107 component of the union contains information relating to a
1108 system call exit stop.
1109 .TP
1110 .B PTRACE_SYSCALL_INFO_SECCOMP
1111 The
1112 .I seccomp
1113 component of the union contains information relating to a
1114 .B PTRACE_EVENT_SECCOMP
1115 stop.
1116 .TP
1117 .B PTRACE_SYSCALL_INFO_NONE
1118 No component of the union contains relevant information.
1119 .RE
1120 .IP
1121 In case of system call entry or exit stops,
1122 the data returned by
1123 .B PTRACE_GET_SYSCALL_INFO
1124 is limited to type
1125 .B PTRACE_SYSCALL_INFO_NONE
1126 unless
1127 .B PTRACE_O_TRACESYSGOOD
1128 option is set before the corresponding system call stop has occurred.
1129 .TP
1130 .BR PTRACE_SET_SYSCALL_INFO " (since Linux 6.16)"
1131 .\" commit 26bb32768fe6552de044f782a58b3272073fbfc0
1132 Modify information about the system call that caused the stop.
1133 The
1134 .I data
1135 argument is a pointer to
1136 .I struct ptrace_syscall_info
1137 that specifies the system call information to be set.
1138 The
1139 .I addr
1140 argument should be set to
1141 .IR "sizeof(struct ptrace_syscall_info)" .
1142 Only the
1143 .IR nr ,
1144 .IR args ,
1145 and
1146 .I rval
1147 fields can be modified.
1148 .\"
1149 .SS Death under ptrace
1150 When a (possibly multithreaded) process receives a killing signal
1151 (one whose disposition is set to
1152 .B SIG_DFL
1153 and whose default action is to kill the process),
1154 all threads exit.
1155 Tracees report their death to their tracer(s).
1156 Notification of this event is delivered via
1157 .BR waitpid (2).
1158 .P
1159 Note that the killing signal will first cause signal-delivery-stop
1160 (on one tracee only),
1161 and only after it is injected by the tracer
1162 (or after it was dispatched to a thread which isn't traced),
1163 will death from the signal happen on
1164 .I all
1165 tracees within a multithreaded process.
1166 (The term "signal-delivery-stop" is explained below.)
1167 .P
1168 .B SIGKILL
1169 does not generate signal-delivery-stop and
1170 therefore the tracer can't suppress it.
1171 .B SIGKILL
1172 kills even within system calls
1173 (syscall-exit-stop is not generated prior to death by
1174 .BR SIGKILL ).
1175 The net effect is that
1176 .B SIGKILL
1177 always kills the process (all its threads),
1178 even if some threads of the process are ptraced.
1179 .P
1180 When the tracee calls
1181 .BR _exit (2),
1182 it reports its death to its tracer.
1183 Other threads are not affected.
1184 .P
1185 When any thread executes
1186 .BR exit_group (2),
1187 every tracee in its thread group reports its death to its tracer.
1188 .P
1189 If the
1190 .B PTRACE_O_TRACEEXIT
1191 option is on,
1192 .B PTRACE_EVENT_EXIT
1193 will happen before actual death.
1194 This applies to exits via
1195 .BR exit (2),
1196 .BR exit_group (2),
1197 and signal deaths (except
1198 .BR SIGKILL ,
1199 depending on the kernel version;
1200 see BUGS below),
1201 and when threads are torn down on
1202 .BR execve (2)
1203 in a multithreaded process.
1204 .P
1205 The tracer cannot assume that the ptrace-stopped tracee exists.
1206 There are many scenarios when the tracee may die while stopped (such as
1207 .BR SIGKILL ).
1208 Therefore, the tracer must be prepared to handle an
1209 .B ESRCH
1210 error on any ptrace operation.
1211 Unfortunately, the same error is returned if the tracee
1212 exists but is not ptrace-stopped
1213 (for commands which require a stopped tracee),
1214 or if it is not traced by the process which issued the ptrace call.
1215 The tracer needs to keep track of the stopped/running state of the tracee,
1216 and interpret
1217 .B ESRCH
1218 as "tracee died unexpectedly" only if it knows that the tracee has
1219 been observed to enter ptrace-stop.
1220 Note that there is no guarantee that
1221 .I waitpid(WNOHANG)
1222 will reliably report the tracee's death status if a
1223 ptrace operation returned
1224 .BR ESRCH .
1225 .I waitpid(WNOHANG)
1226 may return 0 instead.
1227 In other words, the tracee may be "not yet fully dead",
1228 but already refusing ptrace operations.
1229 .P
1230 The tracer can't assume that the tracee
1231 .I always
1232 ends its life by reporting
1233 .I WIFEXITED(status)
1234 or
1235 .IR WIFSIGNALED(status) ;
1236 there are cases where this does not occur.
1237 For example, if a thread other than thread group leader does an
1238 .BR execve (2),
1239 it disappears;
1240 its PID will never be seen again,
1241 and any subsequent ptrace stops will be reported under
1242 the thread group leader's PID.
1243 .SS Stopped states
1244 A tracee can be in two states: running or stopped.
1245 For the purposes of ptrace, a tracee which is blocked in a system call
1246 (such as
1247 .BR read (2),
1248 .BR pause (2),
1249 etc.)
1250 is nevertheless considered to be running, even if the tracee is blocked
1251 for a long time.
1252 The state of the tracee after
1253 .B PTRACE_LISTEN
1254 is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
1255 won't work on it, and it will deliver
1256 .BR waitpid (2)
1257 notifications),
1258 but it also may be considered "stopped" because
1259 it is not executing instructions (is not scheduled), and if it was
1260 in group-stop before
1261 .BR PTRACE_LISTEN ,
1262 it will not respond to signals until
1263 .B SIGCONT
1264 is received.
1265 .P
1266 There are many kinds of states when the tracee is stopped, and in ptrace
1267 discussions they are often conflated.
1268 Therefore, it is important to use precise terms.
1269 .P
1270 In this manual page, any stopped state in which the tracee is ready
1271 to accept ptrace commands from the tracer is called
1272 .IR ptrace-stop .
1273 Ptrace-stops can
1274 be further subdivided into
1275 .IR signal-delivery-stop ,
1276 .IR group-stop ,
1277 .IR syscall-stop ,
1278 .IR "PTRACE_EVENT stops" ,
1279 and so on.
1280 These stopped states are described in detail below.
1281 .P
1282 When the running tracee enters ptrace-stop, it notifies its tracer using
1283 .BR waitpid (2)
1284 (or one of the other "wait" system calls).
1285 Most of this manual page assumes that the tracer waits with:
1286 .P
1287 .in +4n
1288 .EX
1289 pid = waitpid(pid_or_minus_1, &status, __WALL);
1290 .EE
1291 .in
1292 .P
1293 Ptrace-stopped tracees are reported as returns with
1294 .I pid
1295 greater than 0 and
1296 .I WIFSTOPPED(status)
1297 true.
1298 .\" Denys Vlasenko:
1299 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
1300 .\" I am not 100% sure there aren't ugly corner cases.) Are the
1301 .\" rules different if user wants to use waitid? Will waitid require
1302 .\" WEXITED?
1303 .\"
1304 .P
1305 The
1306 .B __WALL
1307 flag does not include the
1308 .B WSTOPPED
1309 and
1310 .B WEXITED
1311 flags, but implies their functionality.
1312 .P
1313 Setting the
1314 .B WCONTINUED
1315 flag when calling
1316 .BR waitpid (2)
1317 is not recommended: the "continued" state is per-process and
1318 consuming it can confuse the real parent of the tracee.
1319 .P
1320 Use of the
1321 .B WNOHANG
1322 flag may cause
1323 .BR waitpid (2)
1324 to return 0 ("no wait results available yet")
1325 even if the tracer knows there should be a notification.
1326 Example:
1327 .P
1328 .in +4n
1329 .EX
1330 errno = 0;
1331 ptrace(PTRACE_CONT, pid, 0L, 0L);
1332 if (errno == ESRCH) {
1333 /* tracee is dead */
1334 r = waitpid(tracee, &status, __WALL | WNOHANG);
1335 /* r can still be 0 here! */
1336 }
1337 .EE
1338 .in
1339 .\" FIXME .
1340 .\" waitid usage? WNOWAIT?
1341 .\" describe how wait notifications queue (or not queue)
1342 .P
1343 The following kinds of ptrace-stops exist: signal-delivery-stops,
1344 group-stops,
1345 .B PTRACE_EVENT
1346 stops, syscall-stops.
1347 They all are reported by
1348 .BR waitpid (2)
1349 with
1350 .I WIFSTOPPED(status)
1351 true.
1352 They may be differentiated by examining the value
1353 .IR status>>8 ,
1354 and if there is ambiguity in that value, by querying
1355 .BR PTRACE_GETSIGINFO .
1356 (Note: the
1357 .I WSTOPSIG(status)
1358 macro can't be used to perform this examination,
1359 because it returns the value
1360 .IR "(status>>8)\ &\ 0xff" .)
1361 .SS Signal-delivery-stop
1362 When a (possibly multithreaded) process receives any signal except
1363 .BR SIGKILL ,
1364 the kernel selects an arbitrary thread which handles the signal.
1365 (If the signal is generated with
1366 .BR tgkill (2),
1367 the target thread can be explicitly selected by the caller.)
1368 If the selected thread is traced, it enters signal-delivery-stop.
1369 At this point, the signal is not yet delivered to the process,
1370 and can be suppressed by the tracer.
1371 If the tracer doesn't suppress the signal,
1372 it passes the signal to the tracee in the next ptrace restart operation.
1373 This second step of signal delivery is called
1374 .I "signal injection"
1375 in this manual page.
1376 Note that if the signal is blocked,
1377 signal-delivery-stop doesn't happen until the signal is unblocked,
1378 with the usual exception that
1379 .B SIGSTOP
1380 can't be blocked.
1381 .P
1382 Signal-delivery-stop is observed by the tracer as
1383 .BR waitpid (2)
1384 returning with
1385 .I WIFSTOPPED(status)
1386 true, with the signal returned by
1387 .IR WSTOPSIG(status) .
1388 If the signal is
1389 .BR SIGTRAP ,
1390 this may be a different kind of ptrace-stop;
1391 see the "Syscall-stops" and "execve" sections below for details.
1392 If
1393 .I WSTOPSIG(status)
1394 returns a stopping signal,
1395 this may be a group-stop;
1396 see below.
1397 .SS Signal injection and suppression
1398 After signal-delivery-stop is observed by the tracer,
1399 the tracer should restart the tracee with the call
1400 .P
1401 .in +4n
1402 .EX
1403 ptrace(PTRACE_restart, pid, 0, sig)
1404 .EE
1405 .in
1406 .P
1407 where
1408 .B PTRACE_restart
1409 is one of the restarting ptrace operations.
1410 If
1411 .I sig
1412 is 0, then a signal is not delivered.
1413 Otherwise, the signal
1414 .I sig
1415 is delivered.
1416 This operation is called
1417 .I "signal injection"
1418 in this manual page, to distinguish it from signal-delivery-stop.
1419 .P
1420 The
1421 .I sig
1422 value may be different from the
1423 .I WSTOPSIG(status)
1424 value: the tracer can cause a different signal to be injected.
1425 .P
1426 Note that a suppressed signal still causes system calls to return
1427 prematurely.
1428 In this case, system calls will be restarted: the tracer will
1429 observe the tracee to reexecute the interrupted system call (or
1430 .BR restart_syscall (2)
1431 system call for a few system calls which use a different mechanism
1432 for restarting) if the tracer uses
1433 .BR PTRACE_SYSCALL .
1434 Even system calls (such as
1435 .BR poll (2))
1436 which are not restartable after signal are restarted after
1437 signal is suppressed;
1438 however, kernel bugs exist which cause some system calls to fail with
1439 .B EINTR
1440 even though no observable signal is injected to the tracee.
1441 .P
1442 Restarting ptrace commands issued in ptrace-stops other than
1443 signal-delivery-stop are not guaranteed to inject a signal, even if
1444 .I sig
1445 is nonzero.
1446 No error is reported;
1447 a nonzero
1448 .I sig
1449 may simply be ignored.
1450 Ptrace users should not try to "create a new signal" this way:
1451 use
1452 .BR tgkill (2)
1453 instead.
1454 .P
1455 The fact that signal injection operations may be ignored
1456 when restarting the tracee after
1457 ptrace stops that are not signal-delivery-stops
1458 is a cause of confusion among ptrace users.
1459 One typical scenario is that the tracer observes group-stop,
1460 mistakes it for signal-delivery-stop, restarts the tracee with
1461 .P
1462 .in +4n
1463 .EX
1464 ptrace(PTRACE_restart, pid, 0, stopsig)
1465 .EE
1466 .in
1467 .P
1468 with the intention of injecting
1469 .IR stopsig ,
1470 but
1471 .I stopsig
1472 gets ignored and the tracee continues to run.
1473 .P
1474 The
1475 .B SIGCONT
1476 signal has a side effect of waking up (all threads of)
1477 a group-stopped process.
1478 This side effect happens before signal-delivery-stop.
1479 The tracer can't suppress this side effect (it can
1480 only suppress signal injection, which only causes the
1481 .B SIGCONT
1482 handler to not be executed in the tracee, if such a handler is installed).
1483 In fact, waking up from group-stop may be followed by
1484 signal-delivery-stop for signal(s)
1485 .I other than
1486 .BR SIGCONT ,
1487 if they were pending when
1488 .B SIGCONT
1489 was delivered.
1490 In other words,
1491 .B SIGCONT
1492 may be not the first signal observed by the tracee after it was sent.
1493 .P
1494 Stopping signals cause (all threads of) a process to enter group-stop.
1495 This side effect happens after signal injection, and therefore can be
1496 suppressed by the tracer.
1497 .P
1498 In Linux 2.4 and earlier, the
1499 .B SIGSTOP
1500 signal can't be injected.
1501 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
1502 .\" there is:
1503 .\"
1504 .\" /* The debugger continued. Ignore SIGSTOP. */
1505 .\" if (signr == SIGSTOP)
1506 .\" continue;
1507 .P
1508 .B PTRACE_GETSIGINFO
1509 can be used to retrieve a
1510 .I siginfo_t
1511 structure which corresponds to the delivered signal.
1512 .B PTRACE_SETSIGINFO
1513 may be used to modify it.
1514 If
1515 .B PTRACE_SETSIGINFO
1516 has been used to alter
1517 .IR siginfo_t ,
1518 the
1519 .I si_signo
1520 field and the
1521 .I sig
1522 parameter in the restarting command must match,
1523 otherwise the result is undefined.
1524 .SS Group-stop
1525 When a (possibly multithreaded) process receives a stopping signal,
1526 all threads stop.
1527 If some threads are traced, they enter a group-stop.
1528 Note that the stopping signal will first cause signal-delivery-stop
1529 (on one tracee only), and only after it is injected by the tracer
1530 (or after it was dispatched to a thread which isn't traced),
1531 will group-stop be initiated on
1532 .I all
1533 tracees within the multithreaded process.
1534 As usual, every tracee reports its group-stop separately
1535 to the corresponding tracer.
1536 .P
1537 Group-stop is observed by the tracer as
1538 .BR waitpid (2)
1539 returning with
1540 .I WIFSTOPPED(status)
1541 true, with the stopping signal available via
1542 .IR WSTOPSIG(status) .
1543 The same result is returned by some other classes of ptrace-stops,
1544 therefore the recommended practice is to perform the call
1545 .P
1546 .in +4n
1547 .EX
1548 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
1549 .EE
1550 .in
1551 .P
1552 The call can be avoided if the signal is not
1553 .BR SIGSTOP ,
1554 .BR SIGTSTP ,
1555 .BR SIGTTIN ,
1556 or
1557 .BR SIGTTOU ;
1558 only these four signals are stopping signals.
1559 If the tracer sees something else, it can't be a group-stop.
1560 Otherwise, the tracer needs to call
1561 .BR PTRACE_GETSIGINFO .
1562 If
1563 .B PTRACE_GETSIGINFO
1564 fails with
1565 .BR EINVAL ,
1566 then it is definitely a group-stop.
1567 (Other failure codes are possible, such as
1568 .B ESRCH
1569 ("no such process") if a
1570 .B SIGKILL
1571 killed the tracee.)
1572 .P
1573 If tracee was attached using
1574 .BR PTRACE_SEIZE ,
1575 group-stop is indicated by
1576 .BR PTRACE_EVENT_STOP :
1577 .IR "status>>16 == PTRACE_EVENT_STOP" .
1578 This allows detection of group-stops
1579 without requiring an extra
1580 .B PTRACE_GETSIGINFO
1581 call.
1582 .P
1583 As of Linux 2.6.38,
1584 after the tracer sees the tracee ptrace-stop and until it
1585 restarts or kills it, the tracee will not run,
1586 and will not send notifications (except
1587 .B SIGKILL
1588 death) to the tracer, even if the tracer enters into another
1589 .BR waitpid (2)
1590 call.
1591 .P
1592 The kernel behavior described in the previous paragraph
1593 causes a problem with transparent handling of stopping signals.
1594 If the tracer restarts the tracee after group-stop,
1595 the stopping signal
1596 is effectively ignored\[em]the tracee doesn't remain stopped, it runs.
1597 If the tracer doesn't restart the tracee before entering into the next
1598 .BR waitpid (2),
1599 future
1600 .B SIGCONT
1601 signals will not be reported to the tracer;
1602 this would cause the
1603 .B SIGCONT
1604 signals to have no effect on the tracee.
1605 .P
1606 Since Linux 3.4, there is a method to overcome this problem: instead of
1607 .BR PTRACE_CONT ,
1608 a
1609 .B PTRACE_LISTEN
1610 command can be used to restart a tracee in a way where it does not execute,
1611 but waits for a new event which it can report via
1612 .BR waitpid (2)
1613 (such as when
1614 it is restarted by a
1615 .BR SIGCONT ).
1616 .SS PTRACE_EVENT stops
1617 If the tracer sets
1618 .B PTRACE_O_TRACE_*
1619 options, the tracee will enter ptrace-stops called
1620 .B PTRACE_EVENT
1621 stops.
1622 .P
1623 .B PTRACE_EVENT
1624 stops are observed by the tracer as
1625 .BR waitpid (2)
1626 returning with
1627 .IR WIFSTOPPED(status) ,
1628 and
1629 .I WSTOPSIG(status)
1630 returns
1631 .B SIGTRAP
1632 (or for
1633 .BR PTRACE_EVENT_STOP ,
1634 returns the stopping signal if tracee is in a group-stop).
1635 An additional bit is set in the higher byte of the status word:
1636 the value
1637 .I status>>8
1638 will be
1639 .P
1640 .in +4n
1641 .EX
1642 ((PTRACE_EVENT_foo<<8) | SIGTRAP).
1643 .EE
1644 .in
1645 .P
1646 The following events exist:
1647 .TP
1648 .B PTRACE_EVENT_VFORK
1649 Stop before return from
1650 .BR vfork (2)
1651 or
1652 .BR clone (2)
1653 with the
1654 .B CLONE_VFORK
1655 flag.
1656 When the tracee is continued after this stop, it will wait for child to
1657 exit/exec before continuing its execution
1658 (in other words, the usual behavior on
1659 .BR vfork (2)).
1660 .TP
1661 .B PTRACE_EVENT_FORK
1662 Stop before return from
1663 .BR fork (2)
1664 or
1665 .BR clone (2)
1666 with the exit signal set to
1667 .BR SIGCHLD .
1668 .TP
1669 .B PTRACE_EVENT_CLONE
1670 Stop before return from
1671 .BR clone (2).
1672 .TP
1673 .B PTRACE_EVENT_VFORK_DONE
1674 Stop before return from
1675 .BR vfork (2)
1676 or
1677 .BR clone (2)
1678 with the
1679 .B CLONE_VFORK
1680 flag,
1681 but after the child unblocked this tracee by exiting or execing.
1682 .P
1683 For all four stops described above,
1684 the stop occurs in the parent (i.e., the tracee),
1685 not in the newly created thread.
1686 .B PTRACE_GETEVENTMSG
1687 can be used to retrieve the new thread's ID.
1688 .TP
1689 .B PTRACE_EVENT_EXEC
1690 Stop before return from
1691 .BR execve (2).
1692 Since Linux 3.0,
1693 .B PTRACE_GETEVENTMSG
1694 returns the former thread ID.
1695 .TP
1696 .B PTRACE_EVENT_EXIT
1697 Stop before exit (including death from
1698 .BR exit_group (2)),
1699 signal death, or exit caused by
1700 .BR execve (2)
1701 in a multithreaded process.
1702 .B PTRACE_GETEVENTMSG
1703 returns the exit status.
1704 Registers can be examined
1705 (unlike when "real" exit happens).
1706 The tracee is still alive;
1707 it needs to be
1708 .BR PTRACE_CONT ed
1709 or
1710 .BR PTRACE_DETACH ed
1711 to finish exiting.
1712 .TP
1713 .B PTRACE_EVENT_STOP
1714 Stop induced by
1715 .B PTRACE_INTERRUPT
1716 command, or group-stop, or initial ptrace-stop when a new child is attached
1717 (only if attached using
1718 .BR PTRACE_SEIZE ).
1719 .TP
1720 .B PTRACE_EVENT_SECCOMP
1721 Stop triggered by a
1722 .BR seccomp (2)
1723 rule on tracee syscall entry when
1724 .B PTRACE_O_TRACESECCOMP
1725 has been set by the tracer.
1726 The seccomp event message data (from the
1727 .B SECCOMP_RET_DATA
1728 portion of the seccomp filter rule) can be retrieved with
1729 .BR PTRACE_GETEVENTMSG .
1730 The semantics of this stop are described in
1731 detail in a separate section below.
1732 .P
1733 .B PTRACE_GETSIGINFO
1734 on
1735 .B PTRACE_EVENT
1736 stops returns
1737 .B SIGTRAP
1738 in
1739 .IR si_signo ,
1740 with
1741 .I si_code
1742 set to
1743 .IR "(event<<8)\ |\ SIGTRAP" .
1744 .SS Syscall-stops
1745 If the tracee was restarted by
1746 .B PTRACE_SYSCALL
1747 or
1748 .BR PTRACE_SYSEMU ,
1749 the tracee enters
1750 syscall-enter-stop just prior to entering any system call (which
1751 will not be executed if the restart was using
1752 .BR PTRACE_SYSEMU ,
1753 regardless of any change made to registers at this point or how the
1754 tracee is restarted after this stop).
1755 No matter which method caused the syscall-entry-stop,
1756 if the tracer restarts the tracee with
1757 .BR PTRACE_SYSCALL ,
1758 the tracee enters syscall-exit-stop when the system call is finished,
1759 or if it is interrupted by a signal.
1760 (That is,
1761 signal-delivery-stop never happens
1762 between syscall-enter-stop and syscall-exit-stop;
1763 it happens
1764 .I after
1765 syscall-exit-stop.).
1766 If the tracee is continued using any other method (including
1767 .BR PTRACE_SYSEMU ),
1768 no syscall-exit-stop occurs.
1769 Note that all mentions
1770 .B PTRACE_SYSEMU
1771 apply equally to
1772 .BR PTRACE_SYSEMU_SINGLESTEP .
1773 .P
1774 However, even if the tracee was continued using
1775 .BR PTRACE_SYSCALL ,
1776 it is not guaranteed that the next stop will be a syscall-exit-stop.
1777 Other possibilities are that the tracee may stop in a
1778 .B PTRACE_EVENT
1779 stop (including seccomp stops), exit (if it entered
1780 .BR _exit (2)
1781 or
1782 .BR exit_group (2)),
1783 be killed by
1784 .BR SIGKILL ,
1785 or die silently (if it is a thread group leader, the
1786 .BR execve (2)
1787 happened in another thread,
1788 and that thread is not traced by the same tracer;
1789 this situation is discussed later).
1790 .P
1791 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1792 .BR waitpid (2)
1793 returning with
1794 .I WIFSTOPPED(status)
1795 true, and
1796 .I WSTOPSIG(status)
1797 giving
1798 .BR SIGTRAP .
1799 If the
1800 .B PTRACE_O_TRACESYSGOOD
1801 option was set by the tracer, then
1802 .I WSTOPSIG(status)
1803 will give the value
1804 .IR "(SIGTRAP\ |\ 0x80)" .
1805 .P
1806 Syscall-stops can be distinguished from signal-delivery-stop with
1807 .B SIGTRAP
1808 by querying
1809 .B PTRACE_GETSIGINFO
1810 for the following cases:
1811 .TP
1812 .IR si_code " <= 0"
1813 .B SIGTRAP
1814 was delivered as a result of a user-space action,
1815 for example, a system call
1816 .RB ( tgkill (2),
1817 .BR kill (2),
1818 .BR sigqueue (3),
1819 etc.),
1820 expiration of a POSIX timer,
1821 change of state on a POSIX message queue,
1822 or completion of an asynchronous I/O operation.
1823 .TP
1824 .IR si_code " == SI_KERNEL (0x80)"
1825 .B SIGTRAP
1826 was sent by the kernel.
1827 .TP
1828 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1829 This is a syscall-stop.
1830 .P
1831 However, syscall-stops happen very often (twice per system call),
1832 and performing
1833 .B PTRACE_GETSIGINFO
1834 for every syscall-stop may be somewhat expensive.
1835 .P
1836 Some architectures allow the cases to be distinguished
1837 by examining registers.
1838 For example, on x86,
1839 .I rax
1840 ==
1841 .RB \- ENOSYS
1842 in syscall-enter-stop.
1843 Since
1844 .B SIGTRAP
1845 (like any other signal) always happens
1846 .I after
1847 syscall-exit-stop,
1848 and at this point
1849 .I rax
1850 almost never contains
1851 .RB \- ENOSYS ,
1852 the
1853 .B SIGTRAP
1854 looks like "syscall-stop which is not syscall-enter-stop";
1855 in other words, it looks like a
1856 "stray syscall-exit-stop" and can be detected this way.
1857 But such detection is fragile and is best avoided.
1858 .P
1859 Using the
1860 .B PTRACE_O_TRACESYSGOOD
1861 option is the recommended method to distinguish syscall-stops
1862 from other kinds of ptrace-stops,
1863 since it is reliable and does not incur a performance penalty.
1864 .P
1865 Syscall-enter-stop and syscall-exit-stop are
1866 indistinguishable from each other by the tracer.
1867 The tracer needs to keep track of the sequence of
1868 ptrace-stops in order to not misinterpret syscall-enter-stop as
1869 syscall-exit-stop or vice versa.
1870 In general, a syscall-enter-stop is
1871 always followed by syscall-exit-stop,
1872 .B PTRACE_EVENT
1873 stop, or the tracee's death;
1874 no other kinds of ptrace-stop can occur in between.
1875 However, note that seccomp stops (see below) can cause syscall-exit-stops,
1876 without preceding syscall-entry-stops.
1877 If seccomp is in use, care needs
1878 to be taken not to misinterpret such stops as syscall-entry-stops.
1879 .P
1880 If after syscall-enter-stop,
1881 the tracer uses a restarting command other than
1882 .BR PTRACE_SYSCALL ,
1883 syscall-exit-stop is not generated.
1884 .P
1885 .B PTRACE_GETSIGINFO
1886 on syscall-stops returns
1887 .B SIGTRAP
1888 in
1889 .IR si_signo ,
1890 with
1891 .I si_code
1892 set to
1893 .B SIGTRAP
1894 or
1895 .IR (SIGTRAP|0x80) .
1896 .\"
1897 .SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to Linux 4.7)
1898 The behavior of
1899 .B PTRACE_EVENT_SECCOMP
1900 stops and their interaction with other kinds
1901 of ptrace stops has changed between kernel versions.
1902 This documents the behavior
1903 from their introduction until Linux 4.7 (inclusive).
1904 The behavior in later kernel versions is documented in the next section.
1905 .P
1906 A
1907 .B PTRACE_EVENT_SECCOMP
1908 stop occurs whenever a
1909 .B SECCOMP_RET_TRACE
1910 rule is triggered.
1911 This is independent of which methods was used to restart the system call.
1912 Notably, seccomp still runs even if the tracee was restarted using
1913 .B PTRACE_SYSEMU
1914 and this system call is unconditionally skipped.
1915 .P
1916 Restarts from this stop will behave as if the stop had occurred right
1917 before the system call in question.
1918 In particular, both
1919 .B PTRACE_SYSCALL
1920 and
1921 .B PTRACE_SYSEMU
1922 will normally cause a subsequent syscall-entry-stop.
1923 However, if after the
1924 .B PTRACE_EVENT_SECCOMP
1925 the system call number is negative,
1926 both the syscall-entry-stop and the system call itself will be skipped.
1927 This means that if the system call number is negative after a
1928 .B PTRACE_EVENT_SECCOMP
1929 and the tracee is restarted using
1930 .BR PTRACE_SYSCALL ,
1931 the next observed stop will be a syscall-exit-stop,
1932 rather than the syscall-entry-stop that might have been expected.
1933 .\"
1934 .SS PTRACE_EVENT_SECCOMP stops (since Linux 4.8)
1935 Starting with Linux 4.8,
1936 .\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea
1937 the
1938 .B PTRACE_EVENT_SECCOMP
1939 stop was reordered to occur between syscall-entry-stop and
1940 syscall-exit-stop.
1941 Note that seccomp no longer runs (and no
1942 .B PTRACE_EVENT_SECCOMP
1943 will be reported) if the system call is skipped due to
1944 .BR PTRACE_SYSEMU .
1945 .P
1946 Functionally, a
1947 .B PTRACE_EVENT_SECCOMP
1948 stop functions comparably
1949 to a syscall-entry-stop (i.e., continuations using
1950 .B PTRACE_SYSCALL
1951 will cause syscall-exit-stops,
1952 the system call number may be changed and any other modified registers
1953 are visible to the to-be-executed system call as well).
1954 Note that there may be,
1955 but need not have been a preceding syscall-entry-stop.
1956 .P
1957 After a
1958 .B PTRACE_EVENT_SECCOMP
1959 stop, seccomp will be rerun, with a
1960 .B SECCOMP_RET_TRACE
1961 rule now functioning the same as a
1962 .BR SECCOMP_RET_ALLOW .
1963 Specifically, this means that if registers are not modified during the
1964 .B PTRACE_EVENT_SECCOMP
1965 stop, the system call will then be allowed.
1966 .\"
1967 .SS PTRACE_SINGLESTEP stops
1968 [Details of these kinds of stops are yet to be documented.]
1969 .\"
1970 .\" FIXME .
1971 .\" document stops occurring with PTRACE_SINGLESTEP
1972 .\"
1973 .SS Informational and restarting ptrace commands
1974 Most ptrace commands (all except
1975 .BR PTRACE_ATTACH ,
1976 .BR PTRACE_SEIZE ,
1977 .BR PTRACE_TRACEME ,
1978 .BR PTRACE_INTERRUPT ,
1979 and
1980 .BR PTRACE_KILL )
1981 require the tracee to be in a ptrace-stop, otherwise they fail with
1982 .BR ESRCH .
1983 .P
1984 When the tracee is in ptrace-stop,
1985 the tracer can read and write data to
1986 the tracee using informational commands.
1987 These commands leave the tracee in ptrace-stopped state:
1988 .P
1989 .in +4n
1990 .EX
1991 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1992 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1993 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1994 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1995 ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
1996 ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
1997 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1998 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1999 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
2000 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
2001 .EE
2002 .in
2003 .P
2004 Note that some errors are not reported.
2005 For example, setting signal information
2006 .RI ( siginfo )
2007 may have no effect in some ptrace-stops, yet the call may succeed
2008 (return 0 and not set
2009 .IR errno );
2010 querying
2011 .B PTRACE_GETEVENTMSG
2012 may succeed and return some random value if current ptrace-stop
2013 is not documented as returning a meaningful event message.
2014 .P
2015 The call
2016 .P
2017 .in +4n
2018 .EX
2019 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
2020 .EE
2021 .in
2022 .P
2023 affects one tracee.
2024 The tracee's current flags are replaced.
2025 Flags are inherited by new tracees created and "auto-attached" via active
2026 .BR PTRACE_O_TRACEFORK ,
2027 .BR PTRACE_O_TRACEVFORK ,
2028 or
2029 .B PTRACE_O_TRACECLONE
2030 options.
2031 .P
2032 Another group of commands makes the ptrace-stopped tracee run.
2033 They have the form:
2034 .P
2035 .in +4n
2036 .EX
2037 ptrace(cmd, pid, 0, sig);
2038 .EE
2039 .in
2040 .P
2041 where
2042 .I cmd
2043 is
2044 .BR PTRACE_CONT ,
2045 .BR PTRACE_LISTEN ,
2046 .BR PTRACE_DETACH ,
2047 .BR PTRACE_SYSCALL ,
2048 .BR PTRACE_SINGLESTEP ,
2049 .BR PTRACE_SYSEMU ,
2050 or
2051 .BR PTRACE_SYSEMU_SINGLESTEP .
2052 If the tracee is in signal-delivery-stop,
2053 .I sig
2054 is the signal to be injected (if it is nonzero).
2055 Otherwise,
2056 .I sig
2057 may be ignored.
2058 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
2059 recommended practice is to always pass 0 in
2060 .IR sig .)
2061 .SS Attaching and detaching
2062 A thread can be attached to the tracer using the call
2063 .P
2064 .in +4n
2065 .EX
2066 ptrace(PTRACE_ATTACH, pid, 0, 0);
2067 .EE
2068 .in
2069 .P
2070 or
2071 .P
2072 .in +4n
2073 .EX
2074 ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
2075 .EE
2076 .in
2077 .P
2078 .B PTRACE_ATTACH
2079 sends
2080 .B SIGSTOP
2081 to this thread.
2082 If the tracer wants this
2083 .B SIGSTOP
2084 to have no effect, it needs to suppress it.
2085 Note that if other signals are concurrently sent to
2086 this thread during attach,
2087 the tracer may see the tracee enter signal-delivery-stop
2088 with other signal(s) first!
2089 The usual practice is to reinject these signals until
2090 .B SIGSTOP
2091 is seen, then suppress
2092 .B SIGSTOP
2093 injection.
2094 The design bug here is that a ptrace attach and a concurrently delivered
2095 .B SIGSTOP
2096 may race and the concurrent
2097 .B SIGSTOP
2098 may be lost.
2099 .\"
2100 .\" FIXME Describe how to attach to a thread which is already group-stopped.
2101 .P
2102 Since attaching sends
2103 .B SIGSTOP
2104 and the tracer usually suppresses it, this may cause a stray
2105 .B EINTR
2106 return from the currently executing system call in the tracee,
2107 as described in the "Signal injection and suppression" section.
2108 .P
2109 Since Linux 3.4,
2110 .B PTRACE_SEIZE
2111 can be used instead of
2112 .BR PTRACE_ATTACH .
2113 .B PTRACE_SEIZE
2114 does not stop the attached process.
2115 If you need to stop
2116 it after attach (or at any other time) without sending it any signals,
2117 use
2118 .B PTRACE_INTERRUPT
2119 command.
2120 .P
2121 The operation
2122 .P
2123 .in +4n
2124 .EX
2125 ptrace(PTRACE_TRACEME, 0, 0, 0);
2126 .EE
2127 .in
2128 .P
2129 turns the calling thread into a tracee.
2130 The thread continues to run (doesn't enter ptrace-stop).
2131 A common practice is to follow the
2132 .B PTRACE_TRACEME
2133 with
2134 .P
2135 .in +4n
2136 .EX
2137 raise(SIGSTOP);
2138 .EE
2139 .in
2140 .P
2141 and allow the parent (which is our tracer now) to observe our
2142 signal-delivery-stop.
2143 .P
2144 If the
2145 .BR PTRACE_O_TRACEFORK ,
2146 .BR PTRACE_O_TRACEVFORK ,
2147 or
2148 .B PTRACE_O_TRACECLONE
2149 options are in effect, then children created by, respectively,
2150 .BR vfork (2)
2151 or
2152 .BR clone (2)
2153 with the
2154 .B CLONE_VFORK
2155 flag,
2156 .BR fork (2)
2157 or
2158 .BR clone (2)
2159 with the exit signal set to
2160 .BR SIGCHLD ,
2161 and other kinds of
2162 .BR clone (2),
2163 are automatically attached to the same tracer which traced their parent.
2164 .B SIGSTOP
2165 is delivered to the children, causing them to enter
2166 signal-delivery-stop after they exit the system call which created them.
2167 .P
2168 Detaching of the tracee is performed by:
2169 .P
2170 .in +4n
2171 .EX
2172 ptrace(PTRACE_DETACH, pid, 0, sig);
2173 .EE
2174 .in
2175 .P
2176 .B PTRACE_DETACH
2177 is a restarting operation;
2178 therefore it requires the tracee to be in ptrace-stop.
2179 If the tracee is in signal-delivery-stop, a signal can be injected.
2180 Otherwise, the
2181 .I sig
2182 parameter may be silently ignored.
2183 .P
2184 If the tracee is running when the tracer wants to detach it,
2185 the usual solution is to send
2186 .B SIGSTOP
2187 (using
2188 .BR tgkill (2),
2189 to make sure it goes to the correct thread),
2190 wait for the tracee to stop in signal-delivery-stop for
2191 .B SIGSTOP
2192 and then detach it (suppressing
2193 .B SIGSTOP
2194 injection).
2195 A design bug is that this can race with concurrent
2196 .BR SIGSTOP s.
2197 Another complication is that the tracee may enter other ptrace-stops
2198 and needs to be restarted and waited for again, until
2199 .B SIGSTOP
2200 is seen.
2201 Yet another complication is to be sure that
2202 the tracee is not already ptrace-stopped,
2203 because no signal delivery happens while it is\[em]not even
2204 .BR SIGSTOP .
2205 .\" FIXME Describe how to detach from a group-stopped tracee so that it
2206 .\" doesn't run, but continues to wait for SIGCONT.
2207 .P
2208 If the tracer dies, all tracees are automatically detached and restarted,
2209 unless they were in group-stop.
2210 Handling of restart from group-stop is currently buggy,
2211 but the "as planned" behavior is to leave tracee stopped and waiting for
2212 .BR SIGCONT .
2213 If the tracee is restarted from signal-delivery-stop,
2214 the pending signal is injected.
2215 .SS execve(2) under ptrace
2216 .\" clone(2) CLONE_THREAD says:
2217 .\" If any of the threads in a thread group performs an execve(2),
2218 .\" then all threads other than the thread group leader are terminated,
2219 .\" and the new program is executed in the thread group leader.
2220 .\"
2221 When one thread in a multithreaded process calls
2222 .BR execve (2),
2223 the kernel destroys all other threads in the process,
2224 .\" In Linux 3.1 sources, see fs/exec.c::de_thread()
2225 and resets the thread ID of the execing thread to the
2226 thread group ID (process ID).
2227 (Or, to put things another way, when a multithreaded process does an
2228 .BR execve (2),
2229 at completion of the call, it appears as though the
2230 .BR execve (2)
2231 occurred in the thread group leader, regardless of which thread did the
2232 .BR execve (2).)
2233 This resetting of the thread ID looks very confusing to tracers:
2234 .IP \[bu] 3
2235 All other threads stop in
2236 .B PTRACE_EVENT_EXIT
2237 stop, if the
2238 .B PTRACE_O_TRACEEXIT
2239 option was turned on.
2240 Then all other threads except the thread group leader report
2241 death as if they exited via
2242 .BR _exit (2)
2243 with exit code 0.
2244 .IP \[bu]
2245 The execing tracee changes its thread ID while it is in the
2246 .BR execve (2).
2247 (Remember, under ptrace, the "pid" returned from
2248 .BR waitpid (2),
2249 or fed into ptrace calls, is the tracee's thread ID.)
2250 That is, the tracee's thread ID is reset to be the same as its process ID,
2251 which is the same as the thread group leader's thread ID.
2252 .IP \[bu]
2253 Then a
2254 .B PTRACE_EVENT_EXEC
2255 stop happens, if the
2256 .B PTRACE_O_TRACEEXEC
2257 option was turned on.
2258 .IP \[bu]
2259 If the thread group leader has reported its
2260 .B PTRACE_EVENT_EXIT
2261 stop by this time,
2262 it appears to the tracer that
2263 the dead thread leader "reappears from nowhere".
2264 (Note: the thread group leader does not report death via
2265 .I WIFEXITED(status)
2266 until there is at least one other live thread.
2267 This eliminates the possibility that the tracer will see
2268 it dying and then reappearing.)
2269 If the thread group leader was still alive,
2270 for the tracer this may look as if thread group leader
2271 returns from a different system call than it entered,
2272 or even "returned from a system call even though
2273 it was not in any system call".
2274 If the thread group leader was not traced
2275 (or was traced by a different tracer), then during
2276 .BR execve (2)
2277 it will appear as if it has become a tracee of
2278 the tracer of the execing tracee.
2279 .P
2280 All of the above effects are the artifacts of
2281 the thread ID change in the tracee.
2282 .P
2283 The
2284 .B PTRACE_O_TRACEEXEC
2285 option is the recommended tool for dealing with this situation.
2286 First, it enables
2287 .B PTRACE_EVENT_EXEC
2288 stop,
2289 which occurs before
2290 .BR execve (2)
2291 returns.
2292 In this stop, the tracer can use
2293 .B PTRACE_GETEVENTMSG
2294 to retrieve the tracee's former thread ID.
2295 (This feature was introduced in Linux 3.0.)
2296 Second, the
2297 .B PTRACE_O_TRACEEXEC
2298 option disables legacy
2299 .B SIGTRAP
2300 generation on
2301 .BR execve (2).
2302 .P
2303 When the tracer receives
2304 .B PTRACE_EVENT_EXEC
2305 stop notification,
2306 it is guaranteed that except this tracee and the thread group leader,
2307 no other threads from the process are alive.
2308 .P
2309 On receiving the
2310 .B PTRACE_EVENT_EXEC
2311 stop notification,
2312 the tracer should clean up all its internal
2313 data structures describing the threads of this process,
2314 and retain only one data structure\[em]one which
2315 describes the single still running tracee, with
2316 .P
2317 .in +4n
2318 .EX
2319 thread ID == thread group ID == process ID.
2320 .EE
2321 .in
2322 .P
2323 Example: two threads call
2324 .BR execve (2)
2325 at the same time:
2326 .P
2327 .nf
2328 *** we get syscall-enter-stop in thread 1: **
2329 PID1 execve("/bin/foo", "foo" <unfinished ...>
2330 *** we issue PTRACE_SYSCALL for thread 1 **
2331 *** we get syscall-enter-stop in thread 2: **
2332 PID2 execve("/bin/bar", "bar" <unfinished ...>
2333 *** we issue PTRACE_SYSCALL for thread 2 **
2334 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
2335 *** we get syscall-exit-stop for PID0: **
2336 PID0 <...\& execve resumed> ) = 0
2337 .fi
2338 .P
2339 If the
2340 .B PTRACE_O_TRACEEXEC
2341 option is
2342 .I not
2343 in effect for the execing tracee,
2344 and if the tracee was
2345 .BR PTRACE_ATTACH ed
2346 rather that
2347 .BR PTRACE_SEIZE d,
2348 the kernel delivers an extra
2349 .B SIGTRAP
2350 to the tracee after
2351 .BR execve (2)
2352 returns.
2353 This is an ordinary signal (similar to one which can be
2354 generated by
2355 .IR "kill \-TRAP" ),
2356 not a special kind of ptrace-stop.
2357 Employing
2358 .B PTRACE_GETSIGINFO
2359 for this signal returns
2360 .I si_code
2361 set to 0
2362 .RI ( SI_USER ).
2363 This signal may be blocked by signal mask,
2364 and thus may be delivered (much) later.
2365 .P
2366 Usually, the tracer (for example,
2367 .BR strace (1))
2368 would not want to show this extra post-execve
2369 .B SIGTRAP
2370 signal to the user, and would suppress its delivery to the tracee (if
2371 .B SIGTRAP
2372 is set to
2373 .BR SIG_DFL ,
2374 it is a killing signal).
2375 However, determining
2376 .I which
2377 .B SIGTRAP
2378 to suppress is not easy.
2379 Setting the
2380 .B PTRACE_O_TRACEEXEC
2381 option or using
2382 .B PTRACE_SEIZE
2383 and thus suppressing this extra
2384 .B SIGTRAP
2385 is the recommended approach.
2386 .SS Real parent
2387 The ptrace API (ab)uses the standard UNIX parent/child signaling over
2388 .BR waitpid (2).
2389 This used to cause the real parent of the process to stop receiving
2390 several kinds of
2391 .BR waitpid (2)
2392 notifications when the child process is traced by some other process.
2393 .P
2394 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
2395 exist;
2396 see BUGS below.
2397 .P
2398 As of Linux 2.6.38, the following is believed to work correctly:
2399 .IP \[bu] 3
2400 exit/death by signal is reported first to the tracer, then,
2401 when the tracer consumes the
2402 .BR waitpid (2)
2403 result, to the real parent (to the real parent only when the
2404 whole multithreaded process exits).
2405 If the tracer and the real parent are the same process,
2406 the report is sent only once.
2407 .SH RETURN VALUE
2408 On success, the
2409 .B PTRACE_PEEK*
2410 operations return the requested data (but see NOTES),
2411 the
2412 .B PTRACE_SECCOMP_GET_FILTER
2413 operation returns the number of instructions in the BPF program,
2414 the
2415 .B PTRACE_GET_SYSCALL_INFO
2416 operation returns the number of bytes available to be written by the kernel,
2417 and other operations return zero.
2418 .P
2419 On error, all operations return \-1, and
2420 .I errno
2421 is set to indicate the error.
2422 Since the value returned by a successful
2423 .B PTRACE_PEEK*
2424 operation may be \-1, the caller must clear
2425 .I errno
2426 before the call, and then check it afterward
2427 to determine whether or not an error occurred.
2428 .SH ERRORS
2429 .TP
2430 .B EBUSY
2431 (i386 only) There was an error with allocating or freeing a debug register.
2432 .TP
2433 .B EFAULT
2434 There was an attempt to read from or write to an invalid area in
2435 the tracer's or the tracee's memory,
2436 probably because the area wasn't mapped or accessible.
2437 Unfortunately, under Linux, different variations of this fault
2438 will return
2439 .B EIO
2440 or
2441 .B EFAULT
2442 more or less arbitrarily.
2443 .TP
2444 .B EINVAL
2445 An attempt was made to set an invalid option.
2446 .TP
2447 .B EIO
2448 .I op
2449 is invalid, or an attempt was made to read from or
2450 write to an invalid area in the tracer's or the tracee's memory,
2451 or there was a word-alignment violation,
2452 or an invalid signal was specified during a restart operation.
2453 .TP
2454 .B EPERM
2455 The specified process cannot be traced.
2456 This could be because the
2457 tracer has insufficient privileges (the required capability is
2458 .BR CAP_SYS_PTRACE );
2459 unprivileged processes cannot trace processes that they
2460 cannot send signals to or those running
2461 set-user-ID/set-group-ID programs, for obvious reasons.
2462 Alternatively, the process may already be being traced,
2463 or (before Linux 2.6.26) be
2464 .BR init (1)
2465 (PID 1).
2466 .TP
2467 .B ESRCH
2468 The specified process does not exist, or is not currently being traced
2469 by the caller, or is not stopped
2470 (for operations that require a stopped tracee).
2471 .SH STANDARDS
2472 None.
2473 .SH HISTORY
2474 SVr4, 4.3BSD.
2475 .P
2476 Before Linux 2.6.26,
2477 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
2478 .BR init (1),
2479 the process with PID 1, may not be traced.
2480 .SH NOTES
2481 Although arguments to
2482 .BR ptrace ()
2483 are interpreted according to the prototype given,
2484 glibc currently declares
2485 .BR ptrace ()
2486 as a variadic function with only the
2487 .I op
2488 argument fixed.
2489 It is recommended to always supply four arguments,
2490 even if the requested operation does not use them,
2491 setting unused/ignored arguments to
2492 .I 0L
2493 or
2494 .IR "(void\ *)\ 0".
2495 .P
2496 A tracees parent continues to be the tracer even if that tracer calls
2497 .BR execve (2).
2498 .P
2499 The layout of the contents of memory and the USER area are
2500 quite operating-system- and architecture-specific.
2501 The offset supplied, and the data returned,
2502 might not entirely match with the definition of
2503 .IR "struct user" .
2504 .\" See http://lkml.org/lkml/2008/5/8/375
2505 .P
2506 The size of a "word" is determined by the operating-system variant
2507 (e.g., for 32-bit Linux it is 32 bits).
2508 .P
2509 This page documents the way the
2510 .BR ptrace ()
2511 call works currently in Linux.
2512 Its behavior differs significantly on other flavors of UNIX.
2513 In any case, use of
2514 .BR ptrace ()
2515 is highly specific to the operating system and architecture.
2516 .\"
2517 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2518 .\"
2519 .SS Ptrace access mode checking
2520 Various parts of the kernel-user-space API (not just
2521 .BR ptrace ()
2522 operations), require so-called "ptrace access mode" checks,
2523 whose outcome determines whether an operation is permitted
2524 (or, in a few cases, causes a "read" operation to return sanitized data).
2525 These checks are performed in cases where one process can
2526 inspect sensitive information about,
2527 or in some cases modify the state of, another process.
2528 The checks are based on factors such as the credentials and capabilities
2529 of the two processes,
2530 whether or not the "target" process is dumpable,
2531 and the results of checks performed by any enabled Linux Security Module
2532 (LSM)\[em]for example, SELinux, Yama, or Smack\[em]and by the commoncap LSM
2533 (which is always invoked).
2534 .P
2535 Prior to Linux 2.6.27, all access checks were of a single type.
2536 Since Linux 2.6.27,
2537 .\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd
2538 two access mode levels are distinguished:
2539 .TP
2540 .B PTRACE_MODE_READ
2541 For "read" operations or other operations that are less dangerous,
2542 such as:
2543 .BR get_robust_list (2);
2544 .BR kcmp (2);
2545 reading
2546 .IR /proc/ pid /auxv ,
2547 .IR /proc/ pid /environ ,
2548 or
2549 .IR /proc/ pid /stat ;
2550 or
2551 .BR readlink (2)
2552 of a
2553 .IR /proc/ pid /ns/*
2554 file.
2555 .TP
2556 .B PTRACE_MODE_ATTACH
2557 For "write" operations, or other operations that are more dangerous,
2558 such as: ptrace attaching
2559 .RB ( PTRACE_ATTACH )
2560 to another process
2561 or calling
2562 .BR process_vm_writev (2).
2563 .RB ( PTRACE_MODE_ATTACH
2564 was effectively the default before Linux 2.6.27.)
2565 .\"
2566 .\" Regarding the above description of the distinction between
2567 .\" PTRACE_MODE_READ and PTRACE_MODE_ATTACH, Stephen Smalley notes:
2568 .\"
2569 .\" That was the intent when the distinction was introduced, but it doesn't
2570 .\" appear to have been properly maintained, e.g., there is now a common
2571 .\" helper lock_trace() that is used for
2572 .\" /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and
2573 .\" PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show(). Likely
2574 .\" should review and make them consistent. There was also some debate
2575 .\" about proper handling of /proc/pid/fd. Arguably that one might belong
2576 .\" back in the _ATTACH camp.
2577 .\"
2578 .P
2579 Since Linux 4.5,
2580 .\" commit caaee6234d05a58c5b4d05e7bf766131b810a657
2581 the above access mode checks are combined (ORed) with
2582 one of the following modifiers:
2583 .TP
2584 .B PTRACE_MODE_FSCREDS
2585 Use the caller's filesystem UID and GID (see
2586 .BR credentials (7))
2587 or effective capabilities for LSM checks.
2588 .TP
2589 .B PTRACE_MODE_REALCREDS
2590 Use the caller's real UID and GID or permitted capabilities for LSM checks.
2591 This was effectively the default before Linux 4.5.
2592 .P
2593 Because combining one of the credential modifiers with one of
2594 the aforementioned access modes is typical,
2595 some macros are defined in the kernel sources for the combinations:
2596 .TP
2597 .B PTRACE_MODE_READ_FSCREDS
2598 Defined as
2599 .BR "PTRACE_MODE_READ | PTRACE_MODE_FSCREDS" .
2600 .TP
2601 .B PTRACE_MODE_READ_REALCREDS
2602 Defined as
2603 .BR "PTRACE_MODE_READ | PTRACE_MODE_REALCREDS" .
2604 .TP
2605 .B PTRACE_MODE_ATTACH_FSCREDS
2606 Defined as
2607 .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS" .
2608 .TP
2609 .B PTRACE_MODE_ATTACH_REALCREDS
2610 Defined as
2611 .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" .
2612 .P
2613 One further modifier can be ORed with the access mode:
2614 .TP
2615 .BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)"
2616 .\" commit 69f594a38967f4540ce7a29b3fd214e68a8330bd
2617 .\" Just for /proc/pid/stat
2618 Don't audit this access mode check.
2619 This modifier is employed for ptrace access mode checks
2620 (such as checks when reading
2621 .IR /proc/ pid /stat )
2622 that merely cause the output to be filtered or sanitized,
2623 rather than causing an error to be returned to the caller.
2624 In these cases, accessing the file is not a security violation and
2625 there is no reason to generate a security audit record.
2626 This modifier suppresses the generation of
2627 such an audit record for the particular access check.
2628 .P
2629 Note that all of the
2630 .B PTRACE_MODE_*
2631 constants described in this subsection are kernel-internal,
2632 and not visible to user space.
2633 The constant names are mentioned here in order to label the various kinds of
2634 ptrace access mode checks that are performed for various system calls
2635 and accesses to various pseudofiles (e.g., under
2636 .IR /proc ).
2637 These names are used in other manual pages to provide a simple
2638 shorthand for labeling the different kernel checks.
2639 .P
2640 The algorithm employed for ptrace access mode checking determines whether
2641 the calling process is allowed to perform the corresponding action
2642 on the target process.
2643 (In the case of opening
2644 .IR /proc/ pid
2645 files, the "calling process" is the one opening the file,
2646 and the process with the corresponding PID is the "target process".)
2647 The algorithm is as follows:
2648 .IP (1) 5
2649 If the calling thread and the target thread are in the same
2650 thread group, access is always allowed.
2651 .IP (2)
2652 If the access mode specifies
2653 .BR PTRACE_MODE_FSCREDS ,
2654 then, for the check in the next step,
2655 employ the caller's filesystem UID and GID.
2656 (As noted in
2657 .BR credentials (7),
2658 the filesystem UID and GID almost always have the same values
2659 as the corresponding effective IDs.)
2660 .IP
2661 Otherwise, the access mode specifies
2662 .BR PTRACE_MODE_REALCREDS ,
2663 so use the caller's real UID and GID for the checks in the next step.
2664 (Most APIs that check the caller's UID and GID use the effective IDs.
2665 For historical reasons, the
2666 .B PTRACE_MODE_REALCREDS
2667 check uses the real IDs instead.)
2668 .IP (3)
2669 Deny access if
2670 .I neither
2671 of the following is true:
2672 .RS
2673 .IP \[bu] 3
2674 The real, effective, and saved-set user IDs of the target
2675 match the caller's user ID,
2676 .I and
2677 the real, effective, and saved-set group IDs of the target
2678 match the caller's group ID.
2679 .IP \[bu]
2680 The caller has the
2681 .B CAP_SYS_PTRACE
2682 capability in the user namespace of the target.
2683 .RE
2684 .IP (4)
2685 Deny access if the target process "dumpable" attribute has a value other than 1
2686 .RB ( SUID_DUMP_USER ;
2687 see the discussion of
2688 .B PR_SET_DUMPABLE
2689 in
2690 .BR prctl (2)),
2691 and the caller does not have the
2692 .B CAP_SYS_PTRACE
2693 capability in the user namespace of the target process.
2694 .IP (5)
2695 The kernel LSM
2696 .IR security_ptrace_access_check ()
2697 interface is invoked to see if ptrace access is permitted.
2698 The results depend on the LSM(s).
2699 The implementation of this interface in the commoncap LSM performs
2700 the following steps:
2701 .\" (in cap_ptrace_access_check()):
2702 .RS
2703 .IP (5.1) 7
2704 If the access mode includes
2705 .BR PTRACE_MODE_FSCREDS ,
2706 then use the caller's
2707 .I effective
2708 capability set
2709 in the following check;
2710 otherwise (the access mode specifies
2711 .BR PTRACE_MODE_REALCREDS ,
2712 so) use the caller's
2713 .I permitted
2714 capability set.
2715 .IP (5.2)
2716 Deny access if
2717 .I neither
2718 of the following is true:
2719 .RS
2720 .IP \[bu] 3
2721 The caller and the target process are in the same user namespace,
2722 and the caller's capabilities are a superset of the target process's
2723 .I permitted
2724 capabilities.
2725 .IP \[bu]
2726 The caller has the
2727 .B CAP_SYS_PTRACE
2728 capability in the target process's user namespace.
2729 .RE
2730 .IP
2731 Note that the commoncap LSM does not distinguish between
2732 .B PTRACE_MODE_READ
2733 and
2734 .BR PTRACE_MODE_ATTACH .
2735 .RE
2736 .IP (6)
2737 If access has not been denied by any of the preceding steps,
2738 then access is allowed.
2739 .\"
2740 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2741 .\"
2742 .SS /proc/sys/kernel/yama/ptrace_scope
2743 On systems with the Yama Linux Security Module (LSM) installed
2744 (i.e., the kernel was configured with
2745 .BR CONFIG_SECURITY_YAMA ),
2746 the
2747 .I /proc/sys/kernel/yama/ptrace_scope
2748 file (available since Linux 3.4)
2749 .\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
2750 can be used to restrict the ability to trace a process with
2751 .BR ptrace ()
2752 (and thus also the ability to use tools such as
2753 .BR strace (1)
2754 and
2755 .BR gdb (1)).
2756 The goal of such restrictions is to prevent attack escalation whereby
2757 a compromised process can ptrace-attach to other sensitive processes
2758 (e.g., a GPG agent or an SSH session) owned by the user in order
2759 to gain additional credentials that may exist in memory
2760 and thus expand the scope of the attack.
2761 .P
2762 More precisely, the Yama LSM limits two types of operations:
2763 .IP \[bu] 3
2764 Any operation that performs a ptrace access mode
2765 .B PTRACE_MODE_ATTACH
2766 check\[em]for example,
2767 .BR ptrace ()
2768 .BR PTRACE_ATTACH .
2769 (See the "Ptrace access mode checking" discussion above.)
2770 .IP \[bu]
2771 .BR ptrace ()
2772 .BR PTRACE_TRACEME .
2773 .P
2774 A process that has the
2775 .B CAP_SYS_PTRACE
2776 capability can update the
2777 .I /proc/sys/kernel/yama/ptrace_scope
2778 file with one of the following values:
2779 .TP
2780 0 ("classic ptrace permissions")
2781 No additional restrictions on operations that perform
2782 .B PTRACE_MODE_ATTACH
2783 checks (beyond those imposed by the commoncap and other LSMs).
2784 .IP
2785 The use of
2786 .B PTRACE_TRACEME
2787 is unchanged.
2788 .TP
2789 1 ("restricted ptrace") [default value]
2790 When performing an operation that requires a
2791 .B PTRACE_MODE_ATTACH
2792 check, the calling process must either have the
2793 .B CAP_SYS_PTRACE
2794 capability in the user namespace of the target process or
2795 it must have a predefined relationship with the target process.
2796 By default,
2797 the predefined relationship is that the target process
2798 must be a descendant of the caller.
2799 .IP
2800 A target process can employ the
2801 .BR prctl (2)
2802 .B PR_SET_PTRACER
2803 operation to declare an additional PID that is allowed to perform
2804 .B PTRACE_MODE_ATTACH
2805 operations on the target.
2806 See the kernel source file
2807 .I Documentation/admin\-guide/LSM/Yama.rst
2808 for further details.
2809 .IP
2810 The use of
2811 .B PTRACE_TRACEME
2812 is unchanged.
2813 .TP
2814 2 ("admin-only attach")
2815 Only processes with the
2816 .B CAP_SYS_PTRACE
2817 capability in the user namespace of the target process may perform
2818 .B PTRACE_MODE_ATTACH
2819 operations or trace children that employ
2820 .BR PTRACE_TRACEME .
2821 .TP
2822 3 ("no attach")
2823 No process may perform
2824 .B PTRACE_MODE_ATTACH
2825 operations or trace children that employ
2826 .BR PTRACE_TRACEME .
2827 .IP
2828 Once this value has been written to the file, it cannot be changed.
2829 .P
2830 With respect to values 1 and 2,
2831 note that creating a new user namespace effectively removes the
2832 protection offered by Yama.
2833 This is because a process in the parent user namespace whose effective
2834 UID matches the UID of the creator of a child namespace
2835 has all capabilities (including
2836 .BR CAP_SYS_PTRACE )
2837 when performing operations within the child user namespace
2838 (and further-removed descendants of that namespace).
2839 Consequently, when a process tries to use user namespaces to sandbox itself,
2840 it inadvertently weakens the protections offered by the Yama LSM.
2841 .\"
2842 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2843 .\"
2844 .SS C library/kernel differences
2845 At the system call level, the
2846 .BR PTRACE_PEEKTEXT ,
2847 .BR PTRACE_PEEKDATA ,
2848 and
2849 .B PTRACE_PEEKUSER
2850 operations have a different API: they store the result
2851 at the address specified by the
2852 .I data
2853 parameter, and the return value is the error flag.
2854 The glibc wrapper function provides the API given in DESCRIPTION above,
2855 with the result being returned via the function return value.
2856 .SH BUGS
2857 On hosts with Linux 2.6 kernel headers,
2858 .B PTRACE_SETOPTIONS
2859 is declared with a different value than the one for Linux 2.4.
2860 This leads to applications compiled with Linux 2.6 kernel
2861 headers failing when run on Linux 2.4.
2862 This can be worked around by redefining
2863 .B PTRACE_SETOPTIONS
2864 to
2865 .BR PTRACE_OLDSETOPTIONS ,
2866 if that is defined.
2867 .P
2868 Group-stop notifications are sent to the tracer, but not to real parent.
2869 Last confirmed on 2.6.38.6.
2870 .P
2871 If a thread group leader is traced and exits by calling
2872 .BR _exit (2),
2873 .\" Note from Denys Vlasenko:
2874 .\" Here "exits" means any kind of death - _exit, exit_group,
2875 .\" signal death. Signal death and exit_group cases are trivial,
2876 .\" though: since signal death and exit_group kill all other threads
2877 .\" too, "until all other threads exit" thing happens rather soon
2878 .\" in these cases. Therefore, only _exit presents observably
2879 .\" puzzling behavior to ptrace users: thread leader _exit's,
2880 .\" but WIFEXITED isn't reported! We are trying to explain here
2881 .\" why it is so.
2882 a
2883 .B PTRACE_EVENT_EXIT
2884 stop will happen for it (if requested), but the subsequent
2885 .B WIFEXITED
2886 notification will not be delivered until all other threads exit.
2887 As explained above, if one of other threads calls
2888 .BR execve (2),
2889 the death of the thread group leader will
2890 .I never
2891 be reported.
2892 If the execed thread is not traced by this tracer,
2893 the tracer will never know that
2894 .BR execve (2)
2895 happened.
2896 One possible workaround is to
2897 .B PTRACE_DETACH
2898 the thread group leader instead of restarting it in this case.
2899 Last confirmed on 2.6.38.6.
2900 .\" FIXME . need to test/verify this scenario
2901 .P
2902 A
2903 .B SIGKILL
2904 signal may still cause a
2905 .B PTRACE_EVENT_EXIT
2906 stop before actual signal death.
2907 This may be changed in the future;
2908 .B SIGKILL
2909 is meant to always immediately kill tasks even under ptrace.
2910 Last confirmed on Linux 3.13.
2911 .P
2912 Some system calls return with
2913 .B EINTR
2914 if a signal was sent to a tracee, but delivery was suppressed by the tracer.
2915 (This is very typical operation: it is usually
2916 done by debuggers on every attach, in order to not introduce
2917 a bogus
2918 .BR SIGSTOP ).
2919 As of Linux 3.2.9, the following system calls are affected
2920 (this list is likely incomplete):
2921 .BR epoll_wait (2),
2922 and
2923 .BR read (2)
2924 from an
2925 .BR inotify (7)
2926 file descriptor.
2927 The usual symptom of this bug is that when you attach to
2928 a quiescent process with the command
2929 .P
2930 .in +4n
2931 .EX
2932 strace \-p <process\-ID>
2933 .EE
2934 .in
2935 .P
2936 then, instead of the usual
2937 and expected one-line output such as
2938 .P
2939 .in +4n
2940 .EX
2941 restart_syscall(<...\& resuming interrupted call ...>_
2942 .EE
2943 .in
2944 .P
2945 or
2946 .P
2947 .in +4n
2948 .EX
2949 select(6, [5], NULL, [5], NULL_
2950 .EE
2951 .in
2952 .P
2953 ('_' denotes the cursor position), you observe more than one line.
2954 For example:
2955 .P
2956 .in +4n
2957 .EX
2958 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
2959 epoll_wait(4,_
2960 .EE
2961 .in
2962 .P
2963 What is not visible here is that the process was blocked in
2964 .BR epoll_wait (2)
2965 before
2966 .BR strace (1)
2967 has attached to it.
2968 Attaching caused
2969 .BR epoll_wait (2)
2970 to return to user space with the error
2971 .BR EINTR .
2972 In this particular case, the program reacted to
2973 .B EINTR
2974 by checking the current time, and then executing
2975 .BR epoll_wait (2)
2976 again.
2977 (Programs which do not expect such "stray"
2978 .B EINTR
2979 errors may behave in an unintended way upon an
2980 .BR strace (1)
2981 attach.)
2982 .P
2983 Contrary to the normal rules, the glibc wrapper for
2984 .BR ptrace ()
2985 can set
2986 .I errno
2987 to zero.
2988 .SH SEE ALSO
2989 .BR gdb (1),
2990 .BR ltrace (1),
2991 .BR strace (1),
2992 .BR clone (2),
2993 .BR execve (2),
2994 .BR fork (2),
2995 .BR gettid (2),
2996 .BR prctl (2),
2997 .BR seccomp (2),
2998 .BR sigaction (2),
2999 .BR tgkill (2),
3000 .BR vfork (2),
3001 .BR waitpid (2),
3002 .BR exec (3),
3003 .BR capabilities (7),
3004 .BR signal (7)