1 .\" Copyright (c) 1993 Michael Haardt <michael@moria.de>
2 .\" Fri Apr 2 11:32:09 MET DST 1993
4 .\" and changes Copyright (C) 1999 Mike Coleman (mkc@acm.org)
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
9 .\" and Copyright (c) 2011, Denys Vlasenko <vda.linux@googlemail.com>
10 .\" and Copyright (c) 2015, 2016, Michael Kerrisk <mtk.manpages@gmail.com>
12 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
13 .\" This is free documentation; you can redistribute it and/or
14 .\" modify it under the terms of the GNU General Public License as
15 .\" published by the Free Software Foundation; either version 2 of
16 .\" the License, or (at your option) any later version.
18 .\" The GNU General Public License's references to "object code"
19 .\" and "executables" are to be interpreted as the output of any
20 .\" document formatting or typesetting system, including
21 .\" intermediate and printed output.
23 .\" This manual is distributed in the hope that it will be useful,
24 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
25 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
26 .\" GNU General Public License for more details.
28 .\" You should have received a copy of the GNU General Public
29 .\" License along with this manual; if not, see
30 .\" <http://www.gnu.org/licenses/>.
33 .\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith <faith@cs.unc.edu>
34 .\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond <esr@thyrsus.com>
35 .\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer <aeb@cwi.nl>
36 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
37 .\" Added notes on capability requirements
39 .\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com>
40 .\" Added PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO,
41 .\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP
42 .\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.)
43 .\" 2011-09, major update by Denys Vlasenko <vda.linux@googlemail.com>
44 .\" 2015-01, Kees Cook <keescook@chromium.org>
45 .\" Added PTRACE_O_TRACESECCOMP, PTRACE_EVENT_SECCOMP
47 .\" FIXME The following are undocumented:
49 .\" PTRACE_GETWMMXREGS
50 .\" PTRACE_SETWMMXREGS
54 .\" PTRACE_SET_SYSCALL
57 .\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f
58 .\" Author: Nicolas Pitre <nico@cam.org>
59 .\" Date: Sat Jan 14 19:30:04 2006 +0000
61 .\" PTRACE_GETCRUNCHREGS
62 .\" PTRACE_SETCRUNCHREGS
65 .\" commit 3bec6ded282b331552587267d67a06ed7fd95ddd
66 .\" Author: Lennert Buytenhek <buytenh@wantstofly.org>
67 .\" Date: Tue Jun 27 22:56:18 2006 +0100
73 .\" commit 3d1228ead618b88e8606015cbabc49019981805d
74 .\" Author: Catalin Marinas <catalin.marinas@arm.com>
75 .\" Date: Wed Feb 11 13:12:56 2009 +0100
81 .\" commit 864232fa1a2f8dfe003438ef0851a56722740f3e
82 .\" Author: Will Deacon <will.deacon@arm.com>
83 .\" Date: Fri Sep 3 10:42:55 2010 +0100
85 .\" PTRACE_SINGLEBLOCK
86 .\" Since at least Linux 2.4.0 on various architectures
87 .\" Since Linux 2.6.25 on x86 (and others?)
88 .\" commit 5b88abbf770a0e1975c668743100f42934f385e8
89 .\" Author: Roland McGrath <roland@redhat.com>
90 .\" Date: Wed Jan 30 13:30:53 2008 +0100
91 .\" ptrace: generic PTRACE_SINGLEBLOCK
95 .\" Since at least Linux 2.4.0 on various architectures
98 .\" PTRACE_GETFDPIC_EXEC
99 .\" PTRACE_GETFDPIC_INTERP
100 .\" blackfin, c6x, frv, sh
101 .\" First appearance in Linux 2.6.11 on frv
103 .\" and others that can be found in the arch/*/include/uapi/asm/ptrace files
105 .TH PTRACE 2 2016-12-12 "Linux" "Linux Programmer's Manual"
107 ptrace \- process trace
110 .B #include <sys/ptrace.h>
112 .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
113 .BI " void *" addr ", void *" data );
118 system call provides a means by which one process (the "tracer")
119 may observe and control the execution of another process (the "tracee"),
120 and examine and change the tracee's memory and registers.
121 It is primarily used to implement breakpoint debugging and system
124 A tracee first needs to be attached to the tracer.
125 Attachment and subsequent commands are per thread:
126 in a multithreaded process,
127 every thread can be individually attached to a
128 (potentially different) tracer,
129 or left not attached and thus not debugged.
130 Therefore, "tracee" always means "(one) thread",
131 never "a (possibly multithreaded) process".
132 Ptrace commands are always sent to
133 a specific tracee using a call of the form
135 ptrace(PTRACE_foo, pid, ...)
139 is the thread ID of the corresponding Linux thread.
141 (Note that in this page, a "multithreaded process"
142 means a thread group consisting of threads created using the
147 A process can initiate a trace by calling
149 and having the resulting child do a
151 followed (typically) by an
153 Alternatively, one process may commence tracing another process using
158 While being traced, the tracee will stop each time a signal is delivered,
159 even if the signal is being ignored.
162 which has its usual effect.)
163 The tracer will be notified at its next call to
165 (or one of the related "wait" system calls); that call will return a
167 value containing information that indicates
168 the cause of the stop in the tracee.
169 While the tracee is stopped,
170 the tracer can use various ptrace requests to inspect and modify the tracee.
171 The tracer then causes the tracee to continue,
172 optionally ignoring the delivered signal
173 (or even delivering a different signal instead).
176 .B PTRACE_O_TRACEEXEC
177 option is not in effect, all successful calls to
179 by the traced process will cause it to be sent a
182 giving the parent a chance to gain control before the new program
185 When the tracer is finished tracing, it can cause the tracee to continue
186 executing in a normal, untraced mode via
191 determines the action to be performed:
194 Indicate that this process is to be traced by its parent.
195 A process probably shouldn't make this request if its parent
196 isn't expecting to trace it.
205 request is used only by the tracee;
206 the remaining requests are used only by the tracer.
207 In the following requests,
209 specifies the thread ID of the tracee to be acted on.
210 For requests other than
213 .BR PTRACE_INTERRUPT ,
216 the tracee must be stopped.
218 .BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA
219 Read a word at the address
221 in the tracee's memory, returning the word as the result of the
224 Linux does not have separate text and data address spaces,
225 so these two requests are currently equivalent.
227 is ignored; but see NOTES.)
230 .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
231 .\" and that is the name that seems common on other systems.
232 Read a word at offset
234 in the tracee's USER area,
235 which holds the registers and other information about the process
238 The word is returned as the result of the
241 Typically, the offset must be word-aligned, though this might vary by
245 is ignored; but see NOTES.)
247 .BR PTRACE_POKETEXT ", " PTRACE_POKEDATA
252 in the tracee's memory.
256 .BR PTRACE_PEEKDATA ,
257 these two requests are currently equivalent.
260 .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
261 .\" and that is the name that seems common on other systems.
266 in the tracee's USER area.
268 .BR PTRACE_PEEKUSER ,
269 the offset must typically be word-aligned.
270 In order to maintain the integrity of the kernel,
271 some modifications to the USER area are disallowed.
272 .\" FIXME In the preceding sentence, which modifications are disallowed,
273 .\" and when they are disallowed, how does user space discover that fact?
275 .BR PTRACE_GETREGS ", " PTRACE_GETFPREGS
276 Copy the tracee's general-purpose or floating-point registers,
277 respectively, to the address
282 for information on the format of this data.
285 Note that SPARC systems have the meaning of
291 is ignored and the registers are copied to the address
296 are not present on all architectures.
298 .BR PTRACE_GETREGSET " (since Linux 2.6.34)"
299 Read the tracee's registers.
301 specifies, in an architecture-dependent way, the type of registers to be read.
303 (with numerical value 1)
304 usually results in reading of general-purpose registers.
305 If the CPU has, for example,
306 floating-point and/or vector registers, they can be retrieved by setting
314 which describes the destination buffer's location and length.
315 On return, the kernel modifies
317 to indicate the actual number of bytes returned.
319 .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
320 Modify the tracee's general-purpose or floating-point registers,
321 respectively, from the address
325 .BR PTRACE_POKEUSER ,
326 some general-purpose register modifications may be disallowed.
327 .\" FIXME . In the preceding sentence, which modifications are disallowed,
328 .\" and when they are disallowed, how does user space discover that fact?
331 Note that SPARC systems have the meaning of
337 is ignored and the registers are copied from the address
342 are not present on all architectures.
344 .BR PTRACE_SETREGSET " (since Linux 2.6.34)"
345 Modify the tracee's registers.
351 .BR PTRACE_GETREGSET .
353 .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
354 Retrieve information about the signal that caused the stop.
359 from the tracee to the address
365 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
366 Set signal information:
369 structure from the address
371 in the tracer to the tracee.
372 This will affect only signals that would normally be delivered to
373 the tracee and were caught by the tracer.
374 It may be difficult to tell
375 these normal signals from synthetic signals generated by
381 .BR PTRACE_PEEKSIGINFO " (since Linux 3.10)"
382 .\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4
385 structures without removing signals from a queue.
388 .I ptrace_peeksiginfo_args
389 structure that specifies the ordinal position from which
390 copying of signals should start,
391 and the number of signals to copy.
393 structures are copied into the buffer pointed to by
395 The return value contains the number of copied signals (zero indicates
396 that there is no signal corresponding to the specified ordinal position).
402 field includes information
405 etc.) that are not otherwise exposed to user space.
409 struct ptrace_peeksiginfo_args {
410 u64 off; /* Ordinal position in queue at which
411 to start copying signals */
412 u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */
413 s32 nr; /* Number of signals to copy */
418 Currently, there is only one flag,
419 .BR PTRACE_PEEKSIGINFO_SHARED ,
420 for dumping signals from the process-wide signal queue.
421 If this flag is not set,
422 signals are read from the per-thread queue of the specified thread.
426 .BR PTRACE_GETSIGMASK " (since Linux 3.11)"
427 .\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
428 Place a copy of the mask of blocked signals (see
430 in the buffer pointed to by
432 which should be a pointer to a buffer of type
436 argument contains the size of the buffer pointed to by
439 .IR sizeof(sigset_t) ).
441 .BR PTRACE_SETSIGMASK " (since Linux 3.11)"
442 Change the mask of blocked signals (see
444 to the value specified in the buffer pointed to by
446 which should be a pointer to a buffer of type
450 argument contains the size of the buffer pointed to by
453 .IR sizeof(sigset_t) ).
455 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
456 Set ptrace options from
461 is interpreted as a bit mask of options,
462 which are specified by the following flags:
465 .BR PTRACE_O_EXITKILL " (since Linux 3.8)"
466 .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123
467 If a tracer sets this flag, a
469 signal will be sent to every tracee if the tracer exits.
470 This option is useful for ptrace jailers that
471 want to ensure that tracees can never escape the tracer's control.
473 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
474 Stop the tracee at the next
476 and automatically start tracing the newly cloned process,
477 which will start with a
486 by the tracer will return a
491 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
494 The PID of the new process can be retrieved with
495 .BR PTRACE_GETEVENTMSG .
497 This option may not catch
505 .B PTRACE_EVENT_VFORK
506 will be delivered instead
508 .B PTRACE_O_TRACEVFORK
509 is set; otherwise if the tracee calls
511 with the exit signal set to
515 .B PTRACE_O_TRACEFORK
518 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
519 Stop the tracee at the next
523 by the tracer will return a
528 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
531 If the execing thread is not a thread group leader,
532 the thread ID is reset to thread group leader's ID before this stop.
533 Since Linux 3.0, the former thread ID can be retrieved with
534 .BR PTRACE_GETEVENTMSG .
536 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
537 Stop the tracee at exit.
540 by the tracer will return a
545 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
548 The tracee's exit status can be retrieved with
549 .BR PTRACE_GETEVENTMSG .
551 The tracee is stopped early during process exit,
552 when registers are still available,
553 allowing the tracer to see where the exit occurred,
554 whereas the normal exit notification is done after the process
556 Even though context is available,
557 the tracer cannot prevent the exit from happening at this point.
559 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
560 Stop the tracee at the next
562 and automatically start tracing the newly forked process,
563 which will start with a
572 by the tracer will return a
577 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
580 The PID of the new process can be retrieved with
581 .BR PTRACE_GETEVENTMSG .
583 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
584 When delivering system call traps, set bit 7 in the signal number
586 .IR "SIGTRAP|0x80" ).
587 This makes it easy for the tracer to distinguish
588 normal traps from those caused by a system call.
589 .RB ( PTRACE_O_TRACESYSGOOD
590 may not work on all architectures.)
592 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
593 Stop the tracee at the next
595 and automatically start tracing the newly vforked process,
596 which will start with a
605 by the tracer will return a
610 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
613 The PID of the new process can be retrieved with
614 .BR PTRACE_GETEVENTMSG .
616 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
617 Stop the tracee at the completion of the next
621 by the tracer will return a
626 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
629 The PID of the new process can (since Linux 2.6.18) be retrieved with
630 .BR PTRACE_GETEVENTMSG .
632 .BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)"
633 Stop the tracee when a
635 .BR SECCOMP_RET_TRACE
639 by the tracer will return a
644 status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))
647 While this triggers a
649 stop, it is similar to a syscall-enter-stop.
650 For details, see the note on
651 .B PTRACE_EVENT_SECCOMP
653 The seccomp event message data (from the
655 portion of the seccomp filter rule) can be retrieved with
656 .BR PTRACE_GETEVENTMSG .
658 .BR PTRACE_O_SUSPEND_SECCOMP " (since Linux 4.3)"
659 .\" commit 13c4a90119d28cfcb6b5bdd820c233b86c2b0237
660 Suspend the tracee's seccomp protections.
661 This applies regardless of mode, and
662 can be used when the tracee has not yet installed seccomp filters.
663 That is, a valid use case is to suspend a tracee's seccomp protections
664 before they are installed by the tracee,
665 let the tracee install the filters,
666 and then clear this flag when the filters should be resumed.
667 Setting this option requires that the tracer have the
670 not have any seccomp protections installed, and not have
671 .BR PTRACE_O_SUSPEND_SECCOMP
675 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
676 Retrieve a message (as an
677 .IR "unsigned long" )
678 about the ptrace event
679 that just happened, placing it at the address
683 .BR PTRACE_EVENT_EXIT ,
684 this is the tracee's exit status.
686 .BR PTRACE_EVENT_FORK ,
687 .BR PTRACE_EVENT_VFORK ,
688 .BR PTRACE_EVENT_VFORK_DONE ,
690 .BR PTRACE_EVENT_CLONE ,
691 this is the PID of the new process.
693 .BR PTRACE_EVENT_SECCOMP ,
698 associated with the triggered rule.
703 Restart the stopped tracee process.
707 it is interpreted as the number of a signal to be delivered to the tracee;
708 otherwise, no signal is delivered.
709 Thus, for example, the tracer can control
710 whether a signal sent to the tracee is delivered or not.
714 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
715 Restart the stopped tracee as for
717 but arrange for the tracee to be stopped at
718 the next entry to or exit from a system call,
719 or after execution of a single instruction, respectively.
720 (The tracee will also, as usual, be stopped upon receipt of a signal.)
721 From the tracer's perspective, the tracee will appear to have been
722 stopped by receipt of a
726 for example, the idea is to inspect
727 the arguments to the system call at the first stop,
730 and inspect the return value of the system call at the second stop.
733 argument is treated as for
738 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
741 continue and stop on entry to the next system call,
742 which will not be executed.
743 See the documentation on syscall-stops below.
745 .BR PTRACE_SYSEMU_SINGLESTEP ,
746 do the same but also singlestep if not a system call.
747 This call is used by programs like
748 User Mode Linux that want to emulate all the tracee's system calls.
751 argument is treated as for
756 These requests are currently
758 supported only on x86.
760 .BR PTRACE_LISTEN " (since Linux 3.4)"
761 Restart the stopped tracee, but prevent it from executing.
762 The resulting state of the tracee is similar to a process which
763 has been stopped by a
765 (or other stopping signal).
766 See the "group-stop" subsection for additional information.
768 works only on tracees attached by
780 .I This operation is deprecated; do not use it!
789 is that it requires the tracee to be in signal-delivery-stop,
790 otherwise it may not work
791 (i.e., may complete successfully but won't kill the tracee).
792 By contrast, sending a
794 directly has no such limitation.
795 .\" [Note from Denys Vlasenko:
796 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
797 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
799 .BR PTRACE_INTERRUPT " (since Linux 3.4)"
801 If the tracee is running or sleeping in kernel space and
804 the system call is interrupted and syscall-exit-stop is reported.
805 (The interrupted system call is restarted when the tracee is restarted.)
806 If the tracee was already stopped by a signal and
809 the tracee stops with
813 returns the stop signal.
814 If any other ptrace-stop is generated at the same time (for example,
815 if a signal is sent to the tracee), this ptrace-stop happens.
816 If none of the above applies (for example, if the tracee is running in user
817 space), it stops with
824 only works on tracees attached by
828 Attach to the process specified in
830 making it a tracee of the calling process.
831 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
832 .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
833 .\" Basically, it's not true for any Linux in practical use.
834 .\" ; the behavior of the tracee is as if it had done a
835 .\" .BR PTRACE_TRACEME .
836 .\" The calling process actually becomes the parent of the tracee
837 .\" process for most purposes (e.g., it will receive
838 .\" notification of tracee events and appears in
840 .\" output as the tracee's parent), but a
842 .\" by the tracee will still return the PID of the original parent.
845 but will not necessarily have stopped
846 by the completion of this call; use
848 to wait for the tracee to stop.
849 See the "Attaching and detaching" subsection for additional information.
855 Permission to perform a
857 is governed by a ptrace access mode
858 .B PTRACE_MODE_ATTACH_REALCREDS
861 .BR PTRACE_SEIZE " (since Linux 3.4)"
863 .\" Noted by Dmitry Levin:
865 .\" PTRACE_SEIZE was introduced by commit v3.1-rc1~308^2~28, but
866 .\" it had to be used along with a temporary flag PTRACE_SEIZE_DEVEL,
867 .\" which was removed later by commit v3.4-rc1~109^2~20.
869 .\" That is, [before] v3.4 we had a test mode of PTRACE_SEIZE API,
870 .\" which was not compatible with the current PTRACE_SEIZE API introduced
873 Attach to the process specified in
875 making it a tracee of the calling process.
879 does not stop the process.
880 Group-stops are reported as
884 returns the stop signal.
885 Automatically attached children stop with
893 signal delivered to them.
895 does not deliver an extra
904 The "seized" behavior just described is inherited by
905 children that are automatically attached using
906 .BR PTRACE_O_TRACEFORK ,
907 .BR PTRACE_O_TRACEVFORK ,
909 .BR PTRACE_O_TRACECLONE .
913 contains a bit mask of ptrace options to activate immediately.
915 Permission to perform a
917 is governed by a ptrace access mode
918 .B PTRACE_MODE_ATTACH_REALCREDS
922 .BR PTRACE_SECCOMP_GET_FILTER " (since Linux 4.4)"
923 .\" commit f8e529ed941ba2bbcbf310b575d968159ce7e895
924 This operation allows the tracer to dump the tracee's
928 is an integer specifying the index of the filter to be dumped.
929 The most recently installed filter has the index 0.
932 is greater than the number of installed filters,
933 the operation fails with the error
937 is either a pointer to a
938 .IR "struct sock_filter"
939 array that is large enough to store the BPF program,
940 or NULL if the program is not to be stored.
943 the return value is the number of instructions in the BPF program.
946 was NULL, then this return value can be used to correctly size the
947 .IR "struct sock_filter"
948 array passed in a subsequent call.
950 This operation fails with the error
952 if the caller does not have the
954 capability or if the caller is in strict or filter seccomp mode.
955 If the filter referred to by
957 is not a classic BPF filter, the operation fails with the error
960 This operation is available if the kernel was configured with both the
961 .B CONFIG_SECCOMP_FILTER
963 .B CONFIG_CHECKPOINT_RESTORE
967 Restart the stopped tracee as for
969 but first detach from it.
970 Under Linux, a tracee can be detached in this way regardless
971 of which method was used to initiate tracing.
976 .BR PTRACE_GET_THREAD_AREA " (since Linux 2.6.0)"
977 This operation performs a similar task to
978 .BR get_thread_area (2).
979 It reads the TLS entry in the GDT whose index is given in
981 placing a copy of the entry into the
982 .IR "struct user_desc"
986 .BR get_thread_area (2),
990 .IR "struct user_desc"
993 .BR PTRACE_SET_THREAD_AREA " (since Linux 2.6.0)"
994 This operation performs a similar task to
995 .BR set_thread_area (2).
996 It sets the TLS entry in the GDT whose index is given in
998 assigning it the data supplied in the
999 .IR "struct user_desc"
1003 .BR set_thread_area (2),
1007 .IR "struct user_desc"
1008 is ignored; in other words,
1009 this ptrace operation can't be used to allocate a free TLS entry.)
1011 .SS Death under ptrace
1012 When a (possibly multithreaded) process receives a killing signal
1013 (one whose disposition is set to
1015 and whose default action is to kill the process),
1017 Tracees report their death to their tracer(s).
1018 Notification of this event is delivered via
1021 Note that the killing signal will first cause signal-delivery-stop
1022 (on one tracee only),
1023 and only after it is injected by the tracer
1024 (or after it was dispatched to a thread which isn't traced),
1025 will death from the signal happen on
1027 tracees within a multithreaded process.
1028 (The term "signal-delivery-stop" is explained below.)
1031 does not generate signal-delivery-stop and
1032 therefore the tracer can't suppress it.
1034 kills even within system calls
1035 (syscall-exit-stop is not generated prior to death by
1037 The net effect is that
1039 always kills the process (all its threads),
1040 even if some threads of the process are ptraced.
1042 When the tracee calls
1044 it reports its death to its tracer.
1045 Other threads are not affected.
1047 When any thread executes
1049 every tracee in its thread group reports its death to its tracer.
1052 .B PTRACE_O_TRACEEXIT
1054 .B PTRACE_EVENT_EXIT
1055 will happen before actual death.
1056 This applies to exits via
1059 and signal deaths (except
1061 depending on the kernel version; see BUGS below),
1062 and when threads are torn down on
1064 in a multithreaded process.
1066 The tracer cannot assume that the ptrace-stopped tracee exists.
1067 There are many scenarios when the tracee may die while stopped (such as
1069 Therefore, the tracer must be prepared to handle an
1071 error on any ptrace operation.
1072 Unfortunately, the same error is returned if the tracee
1073 exists but is not ptrace-stopped
1074 (for commands which require a stopped tracee),
1075 or if it is not traced by the process which issued the ptrace call.
1076 The tracer needs to keep track of the stopped/running state of the tracee,
1079 as "tracee died unexpectedly" only if it knows that the tracee has
1080 been observed to enter ptrace-stop.
1081 Note that there is no guarantee that
1083 will reliably report the tracee's death status if a
1084 ptrace operation returned
1087 may return 0 instead.
1088 In other words, the tracee may be "not yet fully dead",
1089 but already refusing ptrace requests.
1091 The tracer can't assume that the tracee
1093 ends its life by reporting
1094 .I WIFEXITED(status)
1096 .IR WIFSIGNALED(status) ;
1097 there are cases where this does not occur.
1098 For example, if a thread other than thread group leader does an
1101 its PID will never be seen again,
1102 and any subsequent ptrace stops will be reported under
1103 the thread group leader's PID.
1105 A tracee can be in two states: running or stopped.
1106 For the purposes of ptrace, a tracee which is blocked in a system call
1111 is nevertheless considered to be running, even if the tracee is blocked
1113 The state of the tracee after
1115 is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
1116 won't work on it, and it will deliver
1119 but it also may be considered "stopped" because
1120 it is not executing instructions (is not scheduled), and if it was
1121 in group-stop before
1123 it will not respond to signals until
1127 There are many kinds of states when the tracee is stopped, and in ptrace
1128 discussions they are often conflated.
1129 Therefore, it is important to use precise terms.
1131 In this manual page, any stopped state in which the tracee is ready
1132 to accept ptrace commands from the tracer is called
1135 be further subdivided into
1136 .IR signal-delivery-stop ,
1139 .IR PTRACE_EVENT stops,
1141 These stopped states are described in detail below.
1143 When the running tracee enters ptrace-stop, it notifies its tracer using
1145 (or one of the other "wait" system calls).
1146 Most of this manual page assumes that the tracer waits with:
1148 pid = waitpid(pid_or_minus_1, &status, __WALL);
1150 Ptrace-stopped tracees are reported as returns with
1153 .I WIFSTOPPED(status)
1156 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
1157 .\" I am not 100% sure there aren't ugly corner cases.) Are the
1158 .\" rules different if user wants to use waitid? Will waitid require
1164 flag does not include the
1168 flags, but implies their functionality.
1174 is not recommended: the "continued" state is per-process and
1175 consuming it can confuse the real parent of the tracee.
1181 to return 0 ("no wait results available yet")
1182 even if the tracer knows there should be a notification.
1187 ptrace(PTRACE_CONT, pid, 0L, 0L);
1188 if (errno == ESRCH) {
1189 /* tracee is dead */
1190 r = waitpid(tracee, &status, __WALL | WNOHANG);
1191 /* r can still be 0 here! */
1195 .\" waitid usage? WNOWAIT?
1196 .\" describe how wait notifications queue (or not queue)
1198 The following kinds of ptrace-stops exist: signal-delivery-stops,
1201 stops, syscall-stops.
1202 They all are reported by
1205 .I WIFSTOPPED(status)
1207 They may be differentiated by examining the value
1209 and if there is ambiguity in that value, by querying
1210 .BR PTRACE_GETSIGINFO .
1213 macro can't be used to perform this examination,
1214 because it returns the value
1215 .IR "(status>>8)\ &\ 0xff" .)
1216 .SS Signal-delivery-stop
1217 When a (possibly multithreaded) process receives any signal except
1219 the kernel selects an arbitrary thread which handles the signal.
1220 (If the signal is generated with
1222 the target thread can be explicitly selected by the caller.)
1223 If the selected thread is traced, it enters signal-delivery-stop.
1224 At this point, the signal is not yet delivered to the process,
1225 and can be suppressed by the tracer.
1226 If the tracer doesn't suppress the signal,
1227 it passes the signal to the tracee in the next ptrace restart request.
1228 This second step of signal delivery is called
1229 .I "signal injection"
1230 in this manual page.
1231 Note that if the signal is blocked,
1232 signal-delivery-stop doesn't happen until the signal is unblocked,
1233 with the usual exception that
1237 Signal-delivery-stop is observed by the tracer as
1240 .I WIFSTOPPED(status)
1241 true, with the signal returned by
1242 .IR WSTOPSIG(status) .
1245 this may be a different kind of ptrace-stop;
1246 see the "Syscall-stops" and "execve" sections below for details.
1249 returns a stopping signal, this may be a group-stop; see below.
1250 .SS Signal injection and suppression
1251 After signal-delivery-stop is observed by the tracer,
1252 the tracer should restart the tracee with the call
1254 ptrace(PTRACE_restart, pid, 0, sig)
1258 is one of the restarting ptrace requests.
1261 is 0, then a signal is not delivered.
1262 Otherwise, the signal
1265 This operation is called
1266 .I "signal injection"
1267 in this manual page, to distinguish it from signal-delivery-stop.
1271 value may be different from the
1273 value: the tracer can cause a different signal to be injected.
1275 Note that a suppressed signal still causes system calls to return
1277 In this case, system calls will be restarted: the tracer will
1278 observe the tracee to reexecute the interrupted system call (or
1279 .BR restart_syscall (2)
1280 system call for a few system calls which use a different mechanism
1281 for restarting) if the tracer uses
1282 .BR PTRACE_SYSCALL .
1283 Even system calls (such as
1285 which are not restartable after signal are restarted after
1286 signal is suppressed;
1287 however, kernel bugs exist which cause some system calls to fail with
1289 even though no observable signal is injected to the tracee.
1291 Restarting ptrace commands issued in ptrace-stops other than
1292 signal-delivery-stop are not guaranteed to inject a signal, even if
1295 No error is reported; a nonzero
1297 may simply be ignored.
1298 Ptrace users should not try to "create a new signal" this way: use
1302 The fact that signal injection requests may be ignored
1303 when restarting the tracee after
1304 ptrace stops that are not signal-delivery-stops
1305 is a cause of confusion among ptrace users.
1306 One typical scenario is that the tracer observes group-stop,
1307 mistakes it for signal-delivery-stop, restarts the tracee with
1309 ptrace(PTRACE_restart, pid, 0, stopsig)
1311 with the intention of injecting
1315 gets ignored and the tracee continues to run.
1319 signal has a side effect of waking up (all threads of)
1320 a group-stopped process.
1321 This side effect happens before signal-delivery-stop.
1322 The tracer can't suppress this side effect (it can
1323 only suppress signal injection, which only causes the
1325 handler to not be executed in the tracee, if such a handler is installed).
1326 In fact, waking up from group-stop may be followed by
1327 signal-delivery-stop for signal(s)
1330 if they were pending when
1335 may be not the first signal observed by the tracee after it was sent.
1337 Stopping signals cause (all threads of) a process to enter group-stop.
1338 This side effect happens after signal injection, and therefore can be
1339 suppressed by the tracer.
1341 In Linux 2.4 and earlier, the
1343 signal can't be injected.
1344 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
1347 .\" /* The debugger continued. Ignore SIGSTOP. */
1348 .\" if (signr == SIGSTOP)
1351 .B PTRACE_GETSIGINFO
1352 can be used to retrieve a
1354 structure which corresponds to the delivered signal.
1355 .B PTRACE_SETSIGINFO
1356 may be used to modify it.
1358 .B PTRACE_SETSIGINFO
1359 has been used to alter
1365 parameter in the restarting command must match,
1366 otherwise the result is undefined.
1368 When a (possibly multithreaded) process receives a stopping signal,
1370 If some threads are traced, they enter a group-stop.
1371 Note that the stopping signal will first cause signal-delivery-stop
1372 (on one tracee only), and only after it is injected by the tracer
1373 (or after it was dispatched to a thread which isn't traced),
1374 will group-stop be initiated on
1376 tracees within the multithreaded process.
1377 As usual, every tracee reports its group-stop separately
1378 to the corresponding tracer.
1380 Group-stop is observed by the tracer as
1383 .I WIFSTOPPED(status)
1384 true, with the stopping signal available via
1385 .IR WSTOPSIG(status) .
1386 The same result is returned by some other classes of ptrace-stops,
1387 therefore the recommended practice is to perform the call
1389 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
1391 The call can be avoided if the signal is not
1397 only these four signals are stopping signals.
1398 If the tracer sees something else, it can't be a group-stop.
1399 Otherwise, the tracer needs to call
1400 .BR PTRACE_GETSIGINFO .
1402 .B PTRACE_GETSIGINFO
1405 then it is definitely a group-stop.
1406 (Other failure codes are possible, such as
1408 ("no such process") if a
1412 If tracee was attached using
1414 group-stop is indicated by
1415 .BR PTRACE_EVENT_STOP :
1416 .IR "status>>16 == PTRACE_EVENT_STOP" .
1417 This allows detection of group-stops
1418 without requiring an extra
1419 .B PTRACE_GETSIGINFO
1423 after the tracer sees the tracee ptrace-stop and until it
1424 restarts or kills it, the tracee will not run,
1425 and will not send notifications (except
1427 death) to the tracer, even if the tracer enters into another
1431 The kernel behavior described in the previous paragraph
1432 causes a problem with transparent handling of stopping signals.
1433 If the tracer restarts the tracee after group-stop,
1435 is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
1436 If the tracer doesn't restart the tracee before entering into the next
1440 signals will not be reported to the tracer;
1441 this would cause the
1443 signals to have no effect on the tracee.
1445 Since Linux 3.4, there is a method to overcome this problem: instead of
1449 command can be used to restart a tracee in a way where it does not execute,
1450 but waits for a new event which it can report via
1453 it is restarted by a
1455 .SS PTRACE_EVENT stops
1458 options, the tracee will enter ptrace-stops called
1463 stops are observed by the tracer as
1466 .IR WIFSTOPPED(status) ,
1471 An additional bit is set in the higher byte of the status word:
1476 (SIGTRAP | PTRACE_EVENT_foo << 8).
1478 The following events exist:
1480 .B PTRACE_EVENT_VFORK
1481 Stop before return from
1488 When the tracee is continued after this stop, it will wait for child to
1489 exit/exec before continuing its execution
1490 (in other words, the usual behavior on
1493 .B PTRACE_EVENT_FORK
1494 Stop before return from
1498 with the exit signal set to
1501 .B PTRACE_EVENT_CLONE
1502 Stop before return from
1505 .B PTRACE_EVENT_VFORK_DONE
1506 Stop before return from
1513 but after the child unblocked this tracee by exiting or execing.
1515 For all four stops described above,
1516 the stop occurs in the parent (i.e., the tracee),
1517 not in the newly created thread.
1518 .BR PTRACE_GETEVENTMSG
1519 can be used to retrieve the new thread's ID.
1521 .B PTRACE_EVENT_EXEC
1522 Stop before return from
1525 .BR PTRACE_GETEVENTMSG
1526 returns the former thread ID.
1528 .B PTRACE_EVENT_EXIT
1529 Stop before exit (including death from
1530 .BR exit_group (2)),
1531 signal death, or exit caused by
1533 in a multithreaded process.
1534 .B PTRACE_GETEVENTMSG
1535 returns the exit status.
1536 Registers can be examined
1537 (unlike when "real" exit happens).
1538 The tracee is still alive; it needs to be
1541 .BR PTRACE_DETACH ed
1544 .B PTRACE_EVENT_STOP
1547 command, or group-stop, or initial ptrace-stop when a new child is attached
1548 (only if attached using
1551 .B PTRACE_EVENT_SECCOMP
1554 rule on tracee syscall entry when
1555 .BR PTRACE_O_TRACESECCOMP
1556 has been set by the tracer.
1557 The seccomp event message data (from the
1558 .BR SECCOMP_RET_DATA
1559 portion of the seccomp filter rule) can be retrieved with
1560 .BR PTRACE_GETEVENTMSG .
1561 The semantics of this stop are described in
1562 detail in a separate section below.
1564 .B PTRACE_GETSIGINFO
1574 .IR "(event<<8)\ |\ SIGTRAP" .
1576 If the tracee was restarted by
1581 syscall-enter-stop just prior to entering any system call (which
1582 will not be executed if the restart was using
1584 regardless of any change made to registers at this point or how the
1585 tracee is restarted after this stop).
1586 No matter which method caused the syscall-entry-stop,
1587 if the tracer restarts the tracee with
1588 .BR PTRACE_SYSCALL ,
1589 the tracee enters syscall-exit-stop when the system call is finished,
1590 or if it is interrupted by a signal.
1591 (That is, signal-delivery-stop never happens between syscall-enter-stop
1592 and syscall-exit-stop; it happens
1594 syscall-exit-stop.).
1595 If the tracee is continued using any other method (including
1596 .BR PTRACE_SYSEMU ),
1597 no syscall-exit-stop occurs.
1598 Note that all mentions
1601 .BR PTRACE_SYSEMU_SINGLESTEP.
1603 However, even if the tracee was continued using
1605 , it is not guaranteed that the next stop will be a syscall-exit-stop.
1606 Other possibilities are that the tracee may stop in a
1608 stop (including seccomp stops), exit (if it entered
1611 .BR exit_group (2)),
1614 or die silently (if it is a thread group leader, the
1616 happened in another thread,
1617 and that thread is not traced by the same tracer;
1618 this situation is discussed later).
1620 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1623 .I WIFSTOPPED(status)
1629 .B PTRACE_O_TRACESYSGOOD
1630 option was set by the tracer, then
1633 .IR "(SIGTRAP\ |\ 0x80)" .
1635 Syscall-stops can be distinguished from signal-delivery-stop with
1638 .BR PTRACE_GETSIGINFO
1639 for the following cases:
1643 was delivered as a result of a user-space action,
1644 for example, a system call
1649 expiration of a POSIX timer,
1650 change of state on a POSIX message queue,
1651 or completion of an asynchronous I/O request.
1653 .IR si_code " == SI_KERNEL (0x80)"
1655 was sent by the kernel.
1657 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1658 This is a syscall-stop.
1660 However, syscall-stops happen very often (twice per system call),
1662 .B PTRACE_GETSIGINFO
1663 for every syscall-stop may be somewhat expensive.
1665 Some architectures allow the cases to be distinguished
1666 by examining registers.
1667 For example, on x86,
1671 in syscall-enter-stop.
1674 (like any other signal) always happens
1679 almost never contains
1683 looks like "syscall-stop which is not syscall-enter-stop";
1684 in other words, it looks like a
1685 "stray syscall-exit-stop" and can be detected this way.
1686 But such detection is fragile and is best avoided.
1689 .B PTRACE_O_TRACESYSGOOD
1690 option is the recommended method to distinguish syscall-stops
1691 from other kinds of ptrace-stops,
1692 since it is reliable and does not incur a performance penalty.
1694 Syscall-enter-stop and syscall-exit-stop are
1695 indistinguishable from each other by the tracer.
1696 The tracer needs to keep track of the sequence of
1697 ptrace-stops in order to not misinterpret syscall-enter-stop as
1698 syscall-exit-stop or vice versa.
1699 In general, a syscall-enter-stop is
1700 always followed by syscall-exit-stop,
1702 stop, or the tracee's death;
1703 no other kinds of ptrace-stop can occur in between.
1704 However, note that seccomp stops (see below) can cause syscall-exit-stops,
1705 without preceding syscall-entry-stops.
1706 If seccomp is in use, care needs
1707 to be taken not to misinterpret such stops as syscall-entry-stops.
1709 If after syscall-enter-stop,
1710 the tracer uses a restarting command other than
1711 .BR PTRACE_SYSCALL ,
1712 syscall-exit-stop is not generated.
1714 .B PTRACE_GETSIGINFO
1715 on syscall-stops returns
1724 .IR (SIGTRAP|0x80) .
1726 .SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to 4.7)
1728 .BR PTRACE_EVENT_SECCOMP
1729 stops and their interaction with other kinds
1730 of ptrace stops has changed between kernel versions.
1731 This documents the behavior
1732 from their introduction until Linux 4.7 (inclusive).
1733 The behavior in later kernel versions is documented in the next section.
1736 .BR PTRACE_EVENT_SECCOMP
1737 stop occurs whenever a
1738 .BR SECCOMP_RET_TRACE
1740 This is independent of which methods was used to restart the system call.
1741 Notably, seccomp still runs even if the tracee was restarted using
1743 and this system call is unconditionally skipped.
1745 Restarts from this stop will behave as if the stop had occurred right
1746 before the system call in question.
1751 will normally cause a subsequent syscall-entry-stop.
1752 However, if after the
1753 .BR PTRACE_EVENT_SECCOMP
1754 the system call number is negative,
1755 both the syscall-entry-stop and the system call itself will be skipped.
1756 This means that if the system call number is negative after a
1757 .BR PTRACE_EVENT_SECCOMP
1758 and the tracee is restarted using
1760 the next observed stop will be a syscall-exit-stop,
1761 rather than the syscall-entry-stop that might have been expected.
1763 .SS PTRACE_EVENT_SECCOMP stops (since Linux 4.8)
1764 Starting with Linux 4.8,
1765 .\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea
1767 .BR PTRACE_EVENT_SECCOMP
1768 stop was reordered to occur between syscall-entry-stop and
1770 Note that seccomp no longer runs (and no
1771 .B PTRACE_EVENT_SECCOMP
1772 will be reported) if the system call is skipped due to
1776 .B PTRACE_EVENT_SECCOMP
1777 stop functions comparably
1778 to a syscall-entry-stop (i.e., continuations using
1780 will cause syscall-exit-stops,
1781 the system call number may be changed and any other modified registers
1782 are visible to the to-be-executed system call as well).
1783 Note that there may be,
1784 but need not have been a preceding syscall-entry-stop.
1787 .BR PTRACE_EVENT_SECCOMP
1788 stop, seccomp will be rerun, with a
1789 .BR SECCOMP_RET_TRACE
1790 rule now functioning the same as a
1791 .BR SECCOMP_RET_ALLOW .
1792 Specifically, this means that if registers are not modified during the
1793 .BR PTRACE_EVENT_SECCOMP
1794 stop, the system call will then be allowed.
1796 .SS PTRACE_SINGLESTEP stops
1797 [Details of these kinds of stops are yet to be documented.]
1800 .\" document stops occurring with PTRACE_SINGLESTEP
1802 .SS Informational and restarting ptrace commands
1803 Most ptrace commands (all except
1806 .BR PTRACE_TRACEME ,
1807 .BR PTRACE_INTERRUPT ,
1810 require the tracee to be in a ptrace-stop, otherwise they fail with
1813 When the tracee is in ptrace-stop,
1814 the tracer can read and write data to
1815 the tracee using informational commands.
1816 These commands leave the tracee in ptrace-stopped state:
1819 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1820 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1821 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1822 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1823 ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
1824 ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
1825 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1826 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1827 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
1828 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1831 Note that some errors are not reported.
1832 For example, setting signal information
1834 may have no effect in some ptrace-stops, yet the call may succeed
1835 (return 0 and not set
1838 .B PTRACE_GETEVENTMSG
1839 may succeed and return some random value if current ptrace-stop
1840 is not documented as returning a meaningful event message.
1844 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1847 The tracee's current flags are replaced.
1848 Flags are inherited by new tracees created and "auto-attached" via active
1849 .BR PTRACE_O_TRACEFORK ,
1850 .BR PTRACE_O_TRACEVFORK ,
1852 .BR PTRACE_O_TRACECLONE
1855 Another group of commands makes the ptrace-stopped tracee run.
1858 ptrace(cmd, pid, 0, sig);
1866 .BR PTRACE_SYSCALL ,
1867 .BR PTRACE_SINGLESTEP ,
1870 .BR PTRACE_SYSEMU_SINGLESTEP .
1871 If the tracee is in signal-delivery-stop,
1873 is the signal to be injected (if it is nonzero).
1877 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
1878 recommended practice is to always pass 0 in
1880 .SS Attaching and detaching
1881 A thread can be attached to the tracer using the call
1883 ptrace(PTRACE_ATTACH, pid, 0, 0);
1887 ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
1893 If the tracer wants this
1895 to have no effect, it needs to suppress it.
1896 Note that if other signals are concurrently sent to
1897 this thread during attach,
1898 the tracer may see the tracee enter signal-delivery-stop
1899 with other signal(s) first!
1900 The usual practice is to reinject these signals until
1902 is seen, then suppress
1905 The design bug here is that a ptrace attach and a concurrently delivered
1907 may race and the concurrent
1911 .\" FIXME Describe how to attach to a thread which is already group-stopped.
1913 Since attaching sends
1915 and the tracer usually suppresses it, this may cause a stray
1917 return from the currently executing system call in the tracee,
1918 as described in the "Signal injection and suppression" section.
1922 can be used instead of
1925 does not stop the attached process.
1927 it after attach (or at any other time) without sending it any signals,
1934 ptrace(PTRACE_TRACEME, 0, 0, 0);
1936 turns the calling thread into a tracee.
1937 The thread continues to run (doesn't enter ptrace-stop).
1938 A common practice is to follow the
1944 and allow the parent (which is our tracer now) to observe our
1945 signal-delivery-stop.
1948 .BR PTRACE_O_TRACEFORK ,
1949 .BR PTRACE_O_TRACEVFORK ,
1951 .BR PTRACE_O_TRACECLONE
1952 options are in effect, then children created by, respectively,
1962 with the exit signal set to
1966 are automatically attached to the same tracer which traced their parent.
1968 is delivered to the children, causing them to enter
1969 signal-delivery-stop after they exit the system call which created them.
1971 Detaching of the tracee is performed by:
1973 ptrace(PTRACE_DETACH, pid, 0, sig);
1976 is a restarting operation;
1977 therefore it requires the tracee to be in ptrace-stop.
1978 If the tracee is in signal-delivery-stop, a signal can be injected.
1981 parameter may be silently ignored.
1983 If the tracee is running when the tracer wants to detach it,
1984 the usual solution is to send
1988 to make sure it goes to the correct thread),
1989 wait for the tracee to stop in signal-delivery-stop for
1991 and then detach it (suppressing
1994 A design bug is that this can race with concurrent
1996 Another complication is that the tracee may enter other ptrace-stops
1997 and needs to be restarted and waited for again, until
2000 Yet another complication is to be sure that
2001 the tracee is not already ptrace-stopped,
2002 because no signal delivery happens while it is\(emnot even
2004 .\" FIXME Describe how to detach from a group-stopped tracee so that it
2005 .\" doesn't run, but continues to wait for SIGCONT.
2007 If the tracer dies, all tracees are automatically detached and restarted,
2008 unless they were in group-stop.
2009 Handling of restart from group-stop is currently buggy,
2010 but the "as planned" behavior is to leave tracee stopped and waiting for
2012 If the tracee is restarted from signal-delivery-stop,
2013 the pending signal is injected.
2014 .SS execve(2) under ptrace
2015 .\" clone(2) CLONE_THREAD says:
2016 .\" If any of the threads in a thread group performs an execve(2),
2017 .\" then all threads other than the thread group leader are terminated,
2018 .\" and the new program is executed in the thread group leader.
2020 When one thread in a multithreaded process calls
2022 the kernel destroys all other threads in the process,
2023 .\" In kernel 3.1 sources, see fs/exec.c::de_thread()
2024 and resets the thread ID of the execing thread to the
2025 thread group ID (process ID).
2026 (Or, to put things another way, when a multithreaded process does an
2028 at completion of the call, it appears as though the
2030 occurred in the thread group leader, regardless of which thread did the
2032 This resetting of the thread ID looks very confusing to tracers:
2034 All other threads stop in
2035 .B PTRACE_EVENT_EXIT
2037 .BR PTRACE_O_TRACEEXIT
2038 option was turned on.
2039 Then all other threads except the thread group leader report
2040 death as if they exited via
2044 The execing tracee changes its thread ID while it is in the
2046 (Remember, under ptrace, the "pid" returned from
2048 or fed into ptrace calls, is the tracee's thread ID.)
2049 That is, the tracee's thread ID is reset to be the same as its process ID,
2050 which is the same as the thread group leader's thread ID.
2053 .B PTRACE_EVENT_EXEC
2054 stop happens, if the
2055 .BR PTRACE_O_TRACEEXEC
2056 option was turned on.
2058 If the thread group leader has reported its
2059 .B PTRACE_EVENT_EXIT
2061 it appears to the tracer that
2062 the dead thread leader "reappears from nowhere".
2063 (Note: the thread group leader does not report death via
2064 .I WIFEXITED(status)
2065 until there is at least one other live thread.
2066 This eliminates the possibility that the tracer will see
2067 it dying and then reappearing.)
2068 If the thread group leader was still alive,
2069 for the tracer this may look as if thread group leader
2070 returns from a different system call than it entered,
2071 or even "returned from a system call even though
2072 it was not in any system call".
2073 If the thread group leader was not traced
2074 (or was traced by a different tracer), then during
2076 it will appear as if it has become a tracee of
2077 the tracer of the execing tracee.
2079 All of the above effects are the artifacts of
2080 the thread ID change in the tracee.
2083 .B PTRACE_O_TRACEEXEC
2084 option is the recommended tool for dealing with this situation.
2086 .BR PTRACE_EVENT_EXEC
2091 In this stop, the tracer can use
2092 .B PTRACE_GETEVENTMSG
2093 to retrieve the tracee's former thread ID.
2094 (This feature was introduced in Linux 3.0.)
2096 .B PTRACE_O_TRACEEXEC
2097 option disables legacy
2102 When the tracer receives
2103 .B PTRACE_EVENT_EXEC
2105 it is guaranteed that except this tracee and the thread group leader,
2106 no other threads from the process are alive.
2109 .B PTRACE_EVENT_EXEC
2111 the tracer should clean up all its internal
2112 data structures describing the threads of this process,
2113 and retain only one data structure\(emone which
2114 describes the single still running tracee, with
2116 thread ID == thread group ID == process ID.
2118 Example: two threads call
2123 *** we get syscall-enter-stop in thread 1: **
2124 PID1 execve("/bin/foo", "foo" <unfinished ...>
2125 *** we issue PTRACE_SYSCALL for thread 1 **
2126 *** we get syscall-enter-stop in thread 2: **
2127 PID2 execve("/bin/bar", "bar" <unfinished ...>
2128 *** we issue PTRACE_SYSCALL for thread 2 **
2129 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
2130 *** we get syscall-exit-stop for PID0: **
2131 PID0 <... execve resumed> ) = 0
2135 .B PTRACE_O_TRACEEXEC
2138 in effect for the execing tracee,
2139 and if the tracee was
2140 .BR PTRACE_ATTACH ed
2143 the kernel delivers an extra
2148 This is an ordinary signal (similar to one which can be
2151 not a special kind of ptrace-stop.
2153 .B PTRACE_GETSIGINFO
2154 for this signal returns
2158 This signal may be blocked by signal mask,
2159 and thus may be delivered (much) later.
2161 Usually, the tracer (for example,
2163 would not want to show this extra post-execve
2165 signal to the user, and would suppress its delivery to the tracee (if
2169 it is a killing signal).
2170 However, determining
2173 to suppress is not easy.
2175 .B PTRACE_O_TRACEEXEC
2178 and thus suppressing this extra
2180 is the recommended approach.
2182 The ptrace API (ab)uses the standard UNIX parent/child signaling over
2184 This used to cause the real parent of the process to stop receiving
2187 notifications when the child process is traced by some other process.
2189 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
2190 exist; see BUGS below.
2192 As of Linux 2.6.38, the following is believed to work correctly:
2194 exit/death by signal is reported first to the tracer, then,
2195 when the tracer consumes the
2197 result, to the real parent (to the real parent only when the
2198 whole multithreaded process exits).
2199 If the tracer and the real parent are the same process,
2200 the report is sent only once.
2204 requests return the requested data (but see NOTES),
2205 while other requests return zero.
2207 On error, all requests return \-1, and
2209 is set appropriately.
2210 Since the value returned by a successful
2212 request may be \-1, the caller must clear
2214 before the call, and then check it afterward
2215 to determine whether or not an error occurred.
2219 (i386 only) There was an error with allocating or freeing a debug register.
2222 There was an attempt to read from or write to an invalid area in
2223 the tracer's or the tracee's memory,
2224 probably because the area wasn't mapped or accessible.
2225 Unfortunately, under Linux, different variations of this fault
2230 more or less arbitrarily.
2233 An attempt was made to set an invalid option.
2237 is invalid, or an attempt was made to read from or
2238 write to an invalid area in the tracer's or the tracee's memory,
2239 or there was a word-alignment violation,
2240 or an invalid signal was specified during a restart request.
2243 The specified process cannot be traced.
2244 This could be because the
2245 tracer has insufficient privileges (the required capability is
2246 .BR CAP_SYS_PTRACE );
2247 unprivileged processes cannot trace processes that they
2248 cannot send signals to or those running
2249 set-user-ID/set-group-ID programs, for obvious reasons.
2250 Alternatively, the process may already be being traced,
2251 or (on kernels before 2.6.26) be
2256 The specified process does not exist, or is not currently being traced
2257 by the caller, or is not stopped
2258 (for requests that require a stopped tracee).
2262 Although arguments to
2264 are interpreted according to the prototype given,
2265 glibc currently declares
2267 as a variadic function with only the
2270 It is recommended to always supply four arguments,
2271 even if the requested operation does not use them,
2272 setting unused/ignored arguments to
2277 In Linux kernels before 2.6.26,
2278 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
2280 the process with PID 1, may not be traced.
2282 A tracees parent continues to be the tracer even if that tracer calls
2285 The layout of the contents of memory and the USER area are
2286 quite operating-system- and architecture-specific.
2287 The offset supplied, and the data returned,
2288 might not entirely match with the definition of
2290 .\" See http://lkml.org/lkml/2008/5/8/375
2292 The size of a "word" is determined by the operating-system variant
2293 (e.g., for 32-bit Linux it is 32 bits).
2295 This page documents the way the
2297 call works currently in Linux.
2298 Its behavior differs significantly on other flavors of UNIX.
2301 is highly specific to the operating system and architecture.
2303 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2305 .SS Ptrace access mode checking
2306 Various parts of the kernel-user-space API (not just
2308 operations), require so-called "ptrace access mode" checks,
2309 whose outcome determines whether an operation is permitted
2310 (or, in a few cases, causes a "read" operation to return sanitized data).
2311 These checks are performed in cases where one process can
2312 inspect sensitive information about,
2313 or in some cases modify the state of, another process.
2314 The checks are based on factors such as the credentials and capabilities
2315 of the two processes,
2316 whether or not the "target" process is dumpable,
2317 and the results of checks performed by any enabled Linux Security Module
2318 (LSM)\(emfor example, SELinux, Yama, or Smack\(emand by the commoncap LSM
2319 (which is always invoked).
2321 Prior to Linux 2.6.27, all access checks were of a single type.
2323 .\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd
2324 two access mode levels are distinguished:
2326 .BR PTRACE_MODE_READ
2327 For "read" operations or other operations that are less dangerous,
2329 .BR get_robust_list (2);
2332 .IR /proc/[pid]/auxv ,
2333 .IR /proc/[pid]/environ ,
2335 .IR /proc/[pid]/stat ;
2339 .IR /proc/[pid]/ns/*
2342 .BR PTRACE_MODE_ATTACH
2343 For "write" operations, or other operations that are more dangerous,
2344 such as: ptrace attaching
2345 .RB ( PTRACE_ATTACH )
2348 .BR process_vm_writev (2).
2349 .RB ( PTRACE_MODE_ATTACH
2350 was effectively the default before Linux 2.6.27.)
2352 .\" Regarding the above description of the distinction between
2353 .\" PTRACE_MODE_READ and PTRACE_MODE_ATTACH, Stephen Smalley notes:
2355 .\" That was the intent when the distinction was introduced, but it doesn't
2356 .\" appear to have been properly maintained, e.g. there is now a common
2357 .\" helper lock_trace() that is used for
2358 .\" /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and
2359 .\" PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show(). Likely
2360 .\" should review and make them consistent. There was also some debate
2361 .\" about proper handling of /proc/pid/fd. Arguably that one might belong
2362 .\" back in the _ATTACH camp.
2366 .\" commit caaee6234d05a58c5b4d05e7bf766131b810a657
2367 the above access mode checks are combined (ORed) with
2368 one of the following modifiers:
2370 .B PTRACE_MODE_FSCREDS
2371 Use the caller's filesystem UID and GID (see
2372 .BR credentials (7))
2373 or effective capabilities for LSM checks.
2375 .B PTRACE_MODE_REALCREDS
2376 Use the caller's real UID and GID or permitted capabilities for LSM checks.
2377 This was effectively the default before Linux 4.5.
2379 Because combining one of the credential modifiers with one of
2380 the aforementioned access modes is typical,
2381 some macros are defined in the kernel sources for the combinations:
2383 .B PTRACE_MODE_READ_FSCREDS
2385 .BR "PTRACE_MODE_READ | PTRACE_MODE_FSCREDS" .
2387 .B PTRACE_MODE_READ_REALCREDS
2389 .BR "PTRACE_MODE_READ | PTRACE_MODE_REALCREDS" .
2391 .B PTRACE_MODE_ATTACH_FSCREDS
2393 .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS" .
2395 .B PTRACE_MODE_ATTACH_REALCREDS
2397 .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" .
2399 One further modifier can be ORed with the access mode:
2401 .BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)"
2402 .\" commit 69f594a38967f4540ce7a29b3fd214e68a8330bd
2403 .\" Just for /proc/pid/stat
2404 Don't audit this access mode check.
2405 This modifier is employed for ptrace access mode checks
2406 (such as checks when reading
2407 .IR /proc/[pid]/stat )
2408 that merely cause the output to be filtered or sanitized,
2409 rather than causing an error to be returned to the caller.
2410 In these cases, accessing the file is not a security violation and
2411 there is no reason to generate a security audit record.
2412 This modifier suppresses the generation of
2413 such an audit record for the particular access check.
2415 Note that all of the
2417 constants described in this subsection are kernel-internal,
2418 and not visible to user space.
2419 The constant names are mentioned here in order to label the various kinds of
2420 ptrace access mode checks that are performed for various system calls
2421 and accesses to various pseudofiles (e.g., under
2423 These names are used in other manual pages to provide a simple
2424 shorthand for labeling the different kernel checks.
2426 The algorithm employed for ptrace access mode checking determines whether
2427 the calling process is allowed to perform the corresponding action
2428 on the target process.
2429 (In the case of opening
2431 files, the "calling process" is the one opening the file,
2432 and the process with the corresponding PID is the "target process".)
2433 The algorithm is as follows:
2435 If the calling thread and the target thread are in the same
2436 thread group, access is always allowed.
2438 If the access mode specifies
2439 .BR PTRACE_MODE_FSCREDS ,
2440 then, for the check in the next step,
2441 employ the caller's filesystem UID and GID.
2443 .BR credentials (7),
2444 the filesystem UID and GID almost always have the same values
2445 as the corresponding effective IDs.)
2447 Otherwise, the access mode specifies
2448 .BR PTRACE_MODE_REALCREDS ,
2449 so use the caller's real UID and GID for the checks in the next step.
2450 (Most APIs that check the caller's UID and GID use the effective IDs.
2451 For historical reasons, the
2452 .BR PTRACE_MODE_REALCREDS
2453 check uses the real IDs instead.)
2457 of the following is true:
2460 The real, effective, and saved-set user IDs of the target
2461 match the caller's user ID,
2463 the real, effective, and saved-set group IDs of the target
2464 match the caller's group ID.
2468 capability in the user namespace of the target.
2471 Deny access if the target process "dumpable" attribute has a value other than 1
2472 .RB ( SUID_DUMP_USER ;
2473 see the discussion of
2477 and the caller does not have the
2479 capability in the user namespace of the target process.
2482 .IR security_ptrace_access_check ()
2483 interface is invoked to see if ptrace access is permitted.
2484 The results depend on the LSM(s).
2485 The implementation of this interface in the commoncap LSM performs
2486 the following steps:
2487 .\" (in cap_ptrace_access_check()):
2490 If the access mode includes
2491 .BR PTRACE_MODE_FSCREDS ,
2492 then use the caller's
2495 in the following check;
2496 otherwise (the access mode specifies
2497 .BR PTRACE_MODE_REALCREDS ,
2498 so) use the caller's
2504 of the following is true:
2507 The caller and the target process are in the same user namespace,
2508 and the caller's capabilities are a proper superset of the target process's
2514 capability in the target process's user namespace.
2517 Note that the commoncap LSM does not distinguish between
2520 .BR PTRACE_MODE_ATTACH .
2523 If access has not been denied by any of the preceding steps,
2524 then access is allowed.
2526 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2528 .SS /proc/sys/kernel/yama/ptrace_scope
2529 On systems with the Yama Linux Security Module (LSM) installed
2530 (i.e., the kernel was configured with
2531 .BR CONFIG_SECURITY_YAMA ),
2533 .I /proc/sys/kernel/yama/ptrace_scope
2534 file (available since Linux 3.4)
2535 .\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
2536 can be used to restrict the ability to trace a process with
2538 (and thus also the ability to use tools such as
2542 The goal of such restrictions is to prevent attack escalation whereby
2543 a compromised process can ptrace-attach to other sensitive processes
2544 (e.g., a GPG agent or an SSH session) owned by the user in order
2545 to gain additional credentials that may exist in memory
2546 and thus expand the scope of the attack.
2548 More precisely, the Yama LSM limits two types of operations:
2550 Any operation that performs a ptrace access mode
2551 .BR PTRACE_MODE_ATTACH
2552 check\(emfor example,
2555 (See the "Ptrace access mode checking" discussion above.)
2559 .BR PTRACE_TRACEME .
2561 A process that has the
2563 capability can update the
2564 .IR /proc/sys/kernel/yama/ptrace_scope
2565 file with one of the following values:
2567 0 ("classic ptrace permissions")
2568 No additional restrictions on operations that perform
2569 .BR PTRACE_MODE_ATTACH
2570 checks (beyond those imposed by the commoncap and other LSMs).
2576 1 ("restricted ptrace") [default value]
2577 When performing an operation that requires a
2578 .BR PTRACE_MODE_ATTACH
2579 check, the calling process must either have the
2581 capability in the user namespace of the target process or
2582 it must have a predefined relationship with the target process.
2584 the predefined relationship is that the target process
2585 must be a descendant of the caller.
2587 A target process can employ the
2590 operation to declare an additional PID that is allowed to perform
2591 .BR PTRACE_MODE_ATTACH
2592 operations on the target.
2593 See the kernel source file
2594 .IR Documentation/security/Yama.txt
2595 for further details.
2601 2 ("admin-only attach")
2602 Only processes with the
2604 capability in the user namespace of the target process may perform
2605 .BR PTRACE_MODE_ATTACH
2606 operations or trace children that employ
2607 .BR PTRACE_TRACEME .
2610 No process may perform
2611 .BR PTRACE_MODE_ATTACH
2612 operations or trace children that employ
2613 .BR PTRACE_TRACEME .
2615 Once this value has been written to the file, it cannot be changed.
2617 With respect to values 1 and 2,
2618 note that creating a new user namespace effectively removes the
2619 protection offered by Yama.
2620 This is because a process in the parent user namespace whose effective
2621 UID matches the UID of the creator of a child namespace
2622 has all capabilities (including
2623 .BR CAP_SYS_PTRACE )
2624 when performing operations within the child user namespace
2625 (and further-removed descendants of that namespace).
2626 Consequently, when a process tries to use user namespaces to sandbox itself,
2627 it inadvertently weakens the protections offered by the Yama LSM.
2629 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2631 .SS C library/kernel differences
2632 At the system call level, the
2633 .BR PTRACE_PEEKTEXT ,
2634 .BR PTRACE_PEEKDATA ,
2637 requests have a different API: they store the result
2638 at the address specified by the
2640 parameter, and the return value is the error flag.
2641 The glibc wrapper function provides the API given in DESCRIPTION above,
2642 with the result being returned via the function return value.
2644 On hosts with 2.6 kernel headers,
2645 .B PTRACE_SETOPTIONS
2646 is declared with a different value than the one for 2.4.
2647 This leads to applications compiled with 2.6 kernel
2648 headers failing when run on 2.4 kernels.
2649 This can be worked around by redefining
2650 .B PTRACE_SETOPTIONS
2652 .BR PTRACE_OLDSETOPTIONS ,
2655 Group-stop notifications are sent to the tracer, but not to real parent.
2656 Last confirmed on 2.6.38.6.
2658 If a thread group leader is traced and exits by calling
2660 .\" Note from Denys Vlasenko:
2661 .\" Here "exits" means any kind of death - _exit, exit_group,
2662 .\" signal death. Signal death and exit_group cases are trivial,
2663 .\" though: since signal death and exit_group kill all other threads
2664 .\" too, "until all other threads exit" thing happens rather soon
2665 .\" in these cases. Therefore, only _exit presents observably
2666 .\" puzzling behavior to ptrace users: thread leader _exit's,
2667 .\" but WIFEXITED isn't reported! We are trying to explain here
2670 .B PTRACE_EVENT_EXIT
2671 stop will happen for it (if requested), but the subsequent
2673 notification will not be delivered until all other threads exit.
2674 As explained above, if one of other threads calls
2676 the death of the thread group leader will
2679 If the execed thread is not traced by this tracer,
2680 the tracer will never know that
2683 One possible workaround is to
2685 the thread group leader instead of restarting it in this case.
2686 Last confirmed on 2.6.38.6.
2687 .\" FIXME . need to test/verify this scenario
2691 signal may still cause a
2692 .B PTRACE_EVENT_EXIT
2693 stop before actual signal death.
2694 This may be changed in the future;
2696 is meant to always immediately kill tasks even under ptrace.
2697 Last confirmed on Linux 3.13.
2699 Some system calls return with
2701 if a signal was sent to a tracee, but delivery was suppressed by the tracer.
2702 (This is very typical operation: it is usually
2703 done by debuggers on every attach, in order to not introduce
2706 As of Linux 3.2.9, the following system calls are affected
2707 (this list is likely incomplete):
2714 The usual symptom of this bug is that when you attach to
2715 a quiescent process with the command
2717 strace \-p <process-ID>
2719 then, instead of the usual
2720 and expected one-line output such as
2723 restart_syscall(<... resuming interrupted call ...>_
2729 select(6, [5], NULL, [5], NULL_
2732 ('_' denotes the cursor position), you observe more than one line.
2736 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
2740 What is not visible here is that the process was blocked in
2747 to return to user space with the error
2749 In this particular case, the program reacted to
2751 by checking the current time, and then executing
2754 (Programs which do not expect such "stray"
2756 errors may behave in an unintended way upon an
2773 .BR capabilities (7),