Debian Codegraph @

upstream/debian-trixie/man2/ptrace.2

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