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 .\" SPDX-License-Identifier: GPL-2.0-or-later
14 .\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith <faith@cs.unc.edu>
15 .\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond <esr@thyrsus.com>
16 .\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer <aeb@cwi.nl>
17 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
18 .\" Added notes on capability requirements
20 .\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com>
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 <vda.linux@googlemail.com>
25 .\" 2015-01, Kees Cook <keescook@chromium.org>
26 .\" Added PTRACE_O_TRACESECCOMP, PTRACE_EVENT_SECCOMP
28 .\" FIXME The following are undocumented:
30 .\" PTRACE_GETWMMXREGS
31 .\" PTRACE_SETWMMXREGS
35 .\" PTRACE_SET_SYSCALL
38 .\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f
39 .\" Author: Nicolas Pitre <nico@cam.org>
40 .\" Date: Sat Jan 14 19:30:04 2006 +0000
42 .\" PTRACE_GETCRUNCHREGS
43 .\" PTRACE_SETCRUNCHREGS
46 .\" commit 3bec6ded282b331552587267d67a06ed7fd95ddd
47 .\" Author: Lennert Buytenhek <buytenh@wantstofly.org>
48 .\" Date: Tue Jun 27 22:56:18 2006 +0100
54 .\" commit 3d1228ead618b88e8606015cbabc49019981805d
55 .\" Author: Catalin Marinas <catalin.marinas@arm.com>
56 .\" Date: Wed Feb 11 13:12:56 2009 +0100
62 .\" commit 864232fa1a2f8dfe003438ef0851a56722740f3e
63 .\" Author: Will Deacon <will.deacon@arm.com>
64 .\" Date: Fri Sep 3 10:42:55 2010 +0100
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 <roland@redhat.com>
71 .\" Date: Wed Jan 30 13:30:53 2008 +0100
72 .\" ptrace: generic PTRACE_SINGLEBLOCK
76 .\" Since at least Linux 2.4.0 on various architectures
79 .\" PTRACE_GETFDPIC_EXEC
80 .\" PTRACE_GETFDPIC_INTERP
81 .\" blackfin, c6x, frv, sh
82 .\" First appearance in Linux 2.6.11 on frv
84 .\" and others that can be found in the arch/*/include/uapi/asm/ptrace files
86 .TH PTRACE 2 2021-03-22 "Linux" "Linux Programmer's Manual"
88 ptrace \- process trace
91 .RI ( libc ", " \-lc )
94 .B #include <sys/ptrace.h>
96 .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ,
97 .BI " void *" addr ", void *" data );
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
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
121 ptrace(PTRACE_foo, pid, ...)
127 is the thread ID of the corresponding Linux thread.
129 (Note that in this page, a "multithreaded process"
130 means a thread group consisting of threads created using the
135 A process can initiate a trace by calling
137 and having the resulting child do a
139 followed (typically) by an
141 Alternatively, one process may commence tracing another process using
146 While being traced, the tracee will stop each time a signal is delivered,
147 even if the signal is being ignored.
150 which has its usual effect.)
151 The tracer will be notified at its next call to
153 (or one of the related "wait" system calls); that call will return a
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 requests 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).
164 .B PTRACE_O_TRACEEXEC
165 option is not in effect, all successful calls to
167 by the traced process will cause it to be sent a
170 giving the parent a chance to gain control before the new program
173 When the tracer is finished tracing, it can cause the tracee to continue
174 executing in a normal, untraced mode via
179 determines the action to be performed:
182 Indicate that this process is to be traced by its parent.
183 A process probably shouldn't make this request if its parent
184 isn't expecting to trace it.
193 request is used only by the tracee;
194 the remaining requests are used only by the tracer.
195 In the following requests,
197 specifies the thread ID of the tracee to be acted on.
198 For requests other than
201 .BR PTRACE_INTERRUPT ,
204 the tracee must be stopped.
206 .BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA
207 Read a word at the address
209 in the tracee's memory, returning the word as the result of the
212 Linux does not have separate text and data address spaces,
213 so these two requests are currently equivalent.
215 is ignored; but see NOTES.)
218 .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
219 .\" and that is the name that seems common on other systems.
220 Read a word at offset
222 in the tracee's USER area,
223 which holds the registers and other information about the process
226 The word is returned as the result of the
229 Typically, the offset must be word-aligned, though this might vary by
233 is ignored; but see NOTES.)
235 .BR PTRACE_POKETEXT ", " PTRACE_POKEDATA
240 in the tracee's memory.
244 .BR PTRACE_PEEKDATA ,
245 these two requests are currently equivalent.
248 .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
249 .\" and that is the name that seems common on other systems.
254 in the tracee's USER area.
256 .BR PTRACE_PEEKUSER ,
257 the offset must typically be word-aligned.
258 In order to maintain the integrity of the kernel,
259 some modifications to the USER area are disallowed.
260 .\" FIXME In the preceding sentence, which modifications are disallowed,
261 .\" and when they are disallowed, how does user space discover that fact?
263 .BR PTRACE_GETREGS ", " PTRACE_GETFPREGS
264 Copy the tracee's general-purpose or floating-point registers,
265 respectively, to the address
270 for information on the format of this data.
273 Note that SPARC systems have the meaning of
279 is ignored and the registers are copied to the address
284 are not present on all architectures.
286 .BR PTRACE_GETREGSET " (since Linux 2.6.34)"
287 Read the tracee's registers.
289 specifies, in an architecture-dependent way, the type of registers to be read.
291 (with numerical value 1)
292 usually results in reading of general-purpose registers.
293 If the CPU has, for example,
294 floating-point and/or vector registers, they can be retrieved by setting
302 which describes the destination buffer's location and length.
303 On return, the kernel modifies
305 to indicate the actual number of bytes returned.
307 .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
308 Modify the tracee's general-purpose or floating-point registers,
309 respectively, from the address
313 .BR PTRACE_POKEUSER ,
314 some general-purpose register modifications may be disallowed.
315 .\" FIXME . In the preceding sentence, which modifications are disallowed,
316 .\" and when they are disallowed, how does user space discover that fact?
319 Note that SPARC systems have the meaning of
325 is ignored and the registers are copied from the address
330 are not present on all architectures.
332 .BR PTRACE_SETREGSET " (since Linux 2.6.34)"
333 Modify the tracee's registers.
339 .BR PTRACE_GETREGSET .
341 .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
342 Retrieve information about the signal that caused the stop.
347 from the tracee to the address
353 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
354 Set signal information:
357 structure from the address
359 in the tracer to the tracee.
360 This will affect only signals that would normally be delivered to
361 the tracee and were caught by the tracer.
362 It may be difficult to tell
363 these normal signals from synthetic signals generated by
369 .BR PTRACE_PEEKSIGINFO " (since Linux 3.10)"
370 .\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4
373 structures without removing signals from a queue.
376 .I ptrace_peeksiginfo_args
377 structure that specifies the ordinal position from which
378 copying of signals should start,
379 and the number of signals to copy.
381 structures are copied into the buffer pointed to by
383 The return value contains the number of copied signals (zero indicates
384 that there is no signal corresponding to the specified ordinal position).
390 field includes information
393 etc.) that are not otherwise exposed to user space.
397 struct ptrace_peeksiginfo_args {
398 u64 off; /* Ordinal position in queue at which
399 to start copying signals */
400 u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */
401 s32 nr; /* Number of signals to copy */
406 Currently, there is only one flag,
407 .BR PTRACE_PEEKSIGINFO_SHARED ,
408 for dumping signals from the process-wide signal queue.
409 If this flag is not set,
410 signals are read from the per-thread queue of the specified thread.
413 .BR PTRACE_GETSIGMASK " (since Linux 3.11)"
414 .\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
415 Place a copy of the mask of blocked signals (see
417 in the buffer pointed to by
419 which should be a pointer to a buffer of type
423 argument contains the size of the buffer pointed to by
426 .IR sizeof(sigset_t) ).
428 .BR PTRACE_SETSIGMASK " (since Linux 3.11)"
429 Change the mask of blocked signals (see
431 to the value specified in the buffer pointed to by
433 which should be a pointer to a buffer of type
437 argument contains the size of the buffer pointed to by
440 .IR sizeof(sigset_t) ).
442 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
443 Set ptrace options from
448 is interpreted as a bit mask of options,
449 which are specified by the following flags:
452 .BR PTRACE_O_EXITKILL " (since Linux 3.8)"
453 .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123
456 signal to the tracee if the tracer exits.
457 This option is useful for ptrace jailers that
458 want to ensure that tracees can never escape the tracer's control.
460 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
461 Stop the tracee at the next
463 and automatically start tracing the newly cloned process,
464 which will start with a
473 by the tracer will return a
478 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
481 The PID of the new process can be retrieved with
482 .BR PTRACE_GETEVENTMSG .
484 This option may not catch
492 .B PTRACE_EVENT_VFORK
493 will be delivered instead
495 .B PTRACE_O_TRACEVFORK
496 is set; otherwise if the tracee calls
498 with the exit signal set to
502 .B PTRACE_O_TRACEFORK
505 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
506 Stop the tracee at the next
510 by the tracer will return a
515 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
518 If the execing thread is not a thread group leader,
519 the thread ID is reset to thread group leader's ID before this stop.
520 Since Linux 3.0, the former thread ID can be retrieved with
521 .BR PTRACE_GETEVENTMSG .
523 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
524 Stop the tracee at exit.
527 by the tracer will return a
532 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
535 The tracee's exit status can be retrieved with
536 .BR PTRACE_GETEVENTMSG .
538 The tracee is stopped early during process exit,
539 when registers are still available,
540 allowing the tracer to see where the exit occurred,
541 whereas the normal exit notification is done after the process
543 Even though context is available,
544 the tracer cannot prevent the exit from happening at this point.
546 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
547 Stop the tracee at the next
549 and automatically start tracing the newly forked process,
550 which will start with a
559 by the tracer will return a
564 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
567 The PID of the new process can be retrieved with
568 .BR PTRACE_GETEVENTMSG .
570 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
571 When delivering system call traps, set bit 7 in the signal number
573 .IR "SIGTRAP|0x80" ).
574 This makes it easy for the tracer to distinguish
575 normal traps from those caused by a system call.
577 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
578 Stop the tracee at the next
580 and automatically start tracing the newly vforked process,
581 which will start with a
590 by the tracer will return a
595 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
598 The PID of the new process can be retrieved with
599 .BR PTRACE_GETEVENTMSG .
601 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
602 Stop the tracee at the completion of the next
606 by the tracer will return a
611 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
614 The PID of the new process can (since Linux 2.6.18) be retrieved with
615 .BR PTRACE_GETEVENTMSG .
617 .BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)"
618 Stop the tracee when a
624 by the tracer will return a
629 status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))
632 While this triggers a
634 stop, it is similar to a syscall-enter-stop.
635 For details, see the note on
636 .B PTRACE_EVENT_SECCOMP
638 The seccomp event message data (from the
640 portion of the seccomp filter rule) can be retrieved with
641 .BR PTRACE_GETEVENTMSG .
643 .BR PTRACE_O_SUSPEND_SECCOMP " (since Linux 4.3)"
644 .\" commit 13c4a90119d28cfcb6b5bdd820c233b86c2b0237
645 Suspend the tracee's seccomp protections.
646 This applies regardless of mode, and
647 can be used when the tracee has not yet installed seccomp filters.
648 That is, a valid use case is to suspend a tracee's seccomp protections
649 before they are installed by the tracee,
650 let the tracee install the filters,
651 and then clear this flag when the filters should be resumed.
652 Setting this option requires that the tracer have the
655 not have any seccomp protections installed, and not have
656 .B PTRACE_O_SUSPEND_SECCOMP
660 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
661 Retrieve a message (as an
662 .IR "unsigned long" )
663 about the ptrace event
664 that just happened, placing it at the address
668 .BR PTRACE_EVENT_EXIT ,
669 this is the tracee's exit status.
671 .BR PTRACE_EVENT_FORK ,
672 .BR PTRACE_EVENT_VFORK ,
673 .BR PTRACE_EVENT_VFORK_DONE ,
675 .BR PTRACE_EVENT_CLONE ,
676 this is the PID of the new process.
678 .BR PTRACE_EVENT_SECCOMP ,
683 associated with the triggered rule.
688 Restart the stopped tracee process.
692 it is interpreted as the number of a signal to be delivered to the tracee;
693 otherwise, no signal is delivered.
694 Thus, for example, the tracer can control
695 whether a signal sent to the tracee is delivered or not.
699 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
700 Restart the stopped tracee as for
702 but arrange for the tracee to be stopped at
703 the next entry to or exit from a system call,
704 or after execution of a single instruction, respectively.
705 (The tracee will also, as usual, be stopped upon receipt of a signal.)
706 From the tracer's perspective, the tracee will appear to have been
707 stopped by receipt of a
711 for example, the idea is to inspect
712 the arguments to the system call at the first stop,
715 and inspect the return value of the system call at the second stop.
718 argument is treated as for
723 .BR PTRACE_SET_SYSCALL " (since Linux 2.6.16)"
724 .\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f
725 When in syscall-enter-stop,
726 change the number of the system call that is about to
727 be executed to the number specified in the
733 This request is currently
735 supported only on arm (and arm64, though only for backwards compatibility),
736 .\" commit 27aa55c5e5123fa8b8ad0156559d34d7edff58ca
737 but most other architectures have other means of accomplishing this
738 (usually by changing the register that the userland code passed the
739 system call number in).
740 .\" see change_syscall in tools/testing/selftests/seccomp/seccomp_bpf.c
741 .\" and also strace's linux/*/set_scno.c files.
743 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
746 continue and stop on entry to the next system call,
747 which will not be executed.
748 See the documentation on syscall-stops below.
750 .BR PTRACE_SYSEMU_SINGLESTEP ,
751 do the same but also singlestep if not a system call.
752 This call is used by programs like
753 User Mode Linux that want to emulate all the tracee's system calls.
756 argument is treated as for
761 These requests are currently
763 supported only on x86.
765 .BR PTRACE_LISTEN " (since Linux 3.4)"
766 Restart the stopped tracee, but prevent it from executing.
767 The resulting state of the tracee is similar to a process which
768 has been stopped by a
770 (or other stopping signal).
771 See the "group-stop" subsection for additional information.
773 works only on tracees attached by
785 .I This operation is deprecated; do not use it!
794 is that it requires the tracee to be in signal-delivery-stop,
795 otherwise it may not work
796 (i.e., may complete successfully but won't kill the tracee).
797 By contrast, sending a
799 directly has no such limitation.
800 .\" [Note from Denys Vlasenko:
801 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
802 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
804 .BR PTRACE_INTERRUPT " (since Linux 3.4)"
806 If the tracee is running or sleeping in kernel space and
809 the system call is interrupted and syscall-exit-stop is reported.
810 (The interrupted system call is restarted when the tracee is restarted.)
811 If the tracee was already stopped by a signal and
814 the tracee stops with
818 returns the stop signal.
819 If any other ptrace-stop is generated at the same time (for example,
820 if a signal is sent to the tracee), this ptrace-stop happens.
821 If none of the above applies (for example, if the tracee is running in user
822 space), it stops with
829 only works on tracees attached by
833 Attach to the process specified in
835 making it a tracee of the calling process.
836 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
837 .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
838 .\" Basically, it's not true for any Linux in practical use.
839 .\" ; the behavior of the tracee is as if it had done a
840 .\" .BR PTRACE_TRACEME .
841 .\" The calling process actually becomes the parent of the tracee
842 .\" process for most purposes (e.g., it will receive
843 .\" notification of tracee events and appears in
845 .\" output as the tracee's parent), but a
847 .\" by the tracee will still return the PID of the original parent.
850 but will not necessarily have stopped
851 by the completion of this call; use
853 to wait for the tracee to stop.
854 See the "Attaching and detaching" subsection for additional information.
860 Permission to perform a
862 is governed by a ptrace access mode
863 .B PTRACE_MODE_ATTACH_REALCREDS
866 .BR PTRACE_SEIZE " (since Linux 3.4)"
868 .\" Noted by Dmitry Levin:
870 .\" PTRACE_SEIZE was introduced by commit v3.1-rc1~308^2~28, but
871 .\" it had to be used along with a temporary flag PTRACE_SEIZE_DEVEL,
872 .\" which was removed later by commit v3.4-rc1~109^2~20.
874 .\" That is, [before] v3.4 we had a test mode of PTRACE_SEIZE API,
875 .\" which was not compatible with the current PTRACE_SEIZE API introduced
878 Attach to the process specified in
880 making it a tracee of the calling process.
884 does not stop the process.
885 Group-stops are reported as
889 returns the stop signal.
890 Automatically attached children stop with
898 signal delivered to them.
900 does not deliver an extra
909 The "seized" behavior just described is inherited by
910 children that are automatically attached using
911 .BR PTRACE_O_TRACEFORK ,
912 .BR PTRACE_O_TRACEVFORK ,
914 .BR PTRACE_O_TRACECLONE .
918 contains a bit mask of ptrace options to activate immediately.
920 Permission to perform a
922 is governed by a ptrace access mode
923 .B PTRACE_MODE_ATTACH_REALCREDS
927 .BR PTRACE_SECCOMP_GET_FILTER " (since Linux 4.4)"
928 .\" commit f8e529ed941ba2bbcbf310b575d968159ce7e895
929 This operation allows the tracer to dump the tracee's
933 is an integer specifying the index of the filter to be dumped.
934 The most recently installed filter has the index 0.
937 is greater than the number of installed filters,
938 the operation fails with the error
942 is either a pointer to a
943 .I struct sock_filter
944 array that is large enough to store the BPF program,
945 or NULL if the program is not to be stored.
948 the return value is the number of instructions in the BPF program.
951 was NULL, then this return value can be used to correctly size the
952 .I struct sock_filter
953 array passed in a subsequent call.
955 This operation fails with the error
957 if the caller does not have the
959 capability or if the caller is in strict or filter seccomp mode.
960 If the filter referred to by
962 is not a classic BPF filter, the operation fails with the error
965 This operation is available if the kernel was configured with both the
966 .B CONFIG_SECCOMP_FILTER
968 .B CONFIG_CHECKPOINT_RESTORE
972 Restart the stopped tracee as for
974 but first detach from it.
975 Under Linux, a tracee can be detached in this way regardless
976 of which method was used to initiate tracing.
981 .BR PTRACE_GET_THREAD_AREA " (since Linux 2.6.0)"
982 This operation performs a similar task to
983 .BR get_thread_area (2).
984 It reads the TLS entry in the GDT whose index is given in
986 placing a copy of the entry into the
991 .BR get_thread_area (2),
998 .BR PTRACE_SET_THREAD_AREA " (since Linux 2.6.0)"
999 This operation performs a similar task to
1000 .BR set_thread_area (2).
1001 It sets the TLS entry in the GDT whose index is given in
1003 assigning it the data supplied in the
1008 .BR set_thread_area (2),
1013 is ignored; in other words,
1014 this ptrace operation can't be used to allocate a free TLS entry.)
1016 .BR PTRACE_GET_SYSCALL_INFO " (since Linux 5.3)"
1017 .\" commit 201766a20e30f982ccfe36bebfad9602c3ff574a
1018 Retrieve information about the system call that caused the stop.
1019 The information is placed into the buffer pointed by the
1021 argument, which should be a pointer to a buffer of type
1022 .IR "struct ptrace_syscall_info" .
1025 argument contains the size of the buffer pointed to
1029 .IR "sizeof(struct ptrace_syscall_info)" ).
1030 The return value contains the number of bytes available
1031 to be written by the kernel.
1032 If the size of the data to be written by the kernel exceeds the size
1035 argument, the output data is truncated.
1038 .I ptrace_syscall_info
1039 structure contains the following fields:
1043 struct ptrace_syscall_info {
1044 __u8 op; /* Type of system call stop */
1045 __u32 arch; /* AUDIT_ARCH_* value; see seccomp(2) */
1046 __u64 instruction_pointer; /* CPU instruction pointer */
1047 __u64 stack_pointer; /* CPU stack pointer */
1049 struct { /* op == PTRACE_SYSCALL_INFO_ENTRY */
1050 __u64 nr; /* System call number */
1051 __u64 args[6]; /* System call arguments */
1053 struct { /* op == PTRACE_SYSCALL_INFO_EXIT */
1054 __s64 rval; /* System call return value */
1055 __u8 is_error; /* System call error flag;
1056 Boolean: does rval contain
1057 an error value (\-ERRCODE) or
1058 a nonerror return value? */
1060 struct { /* op == PTRACE_SYSCALL_INFO_SECCOMP */
1061 __u64 nr; /* System call number */
1062 __u64 args[6]; /* System call arguments */
1063 __u32 ret_data; /* SECCOMP_RET_DATA portion
1064 of SECCOMP_RET_TRACE
1075 .IR instruction_pointer ,
1078 fields are defined for all kinds of ptrace system call stops.
1079 The rest of the structure is a union; one should read only those fields
1080 that are meaningful for the kind of system call stop specified by the
1086 field has one of the following values (defined in
1087 .IR <linux/ptrace.h> )
1088 indicating what type of stop occurred and
1089 which part of the union is filled:
1092 .B PTRACE_SYSCALL_INFO_ENTRY
1095 component of the union contains information relating to a
1096 system call entry stop.
1098 .B PTRACE_SYSCALL_INFO_EXIT
1101 component of the union contains information relating to a
1102 system call exit stop.
1104 .B PTRACE_SYSCALL_INFO_SECCOMP
1107 component of the union contains information relating to a
1108 .B PTRACE_EVENT_SECCOMP
1111 .B PTRACE_SYSCALL_INFO_NONE
1112 No component of the union contains relevant information.
1115 .SS Death under ptrace
1116 When a (possibly multithreaded) process receives a killing signal
1117 (one whose disposition is set to
1119 and whose default action is to kill the process),
1121 Tracees report their death to their tracer(s).
1122 Notification of this event is delivered via
1125 Note that the killing signal will first cause signal-delivery-stop
1126 (on one tracee only),
1127 and only after it is injected by the tracer
1128 (or after it was dispatched to a thread which isn't traced),
1129 will death from the signal happen on
1131 tracees within a multithreaded process.
1132 (The term "signal-delivery-stop" is explained below.)
1135 does not generate signal-delivery-stop and
1136 therefore the tracer can't suppress it.
1138 kills even within system calls
1139 (syscall-exit-stop is not generated prior to death by
1141 The net effect is that
1143 always kills the process (all its threads),
1144 even if some threads of the process are ptraced.
1146 When the tracee calls
1148 it reports its death to its tracer.
1149 Other threads are not affected.
1151 When any thread executes
1153 every tracee in its thread group reports its death to its tracer.
1156 .B PTRACE_O_TRACEEXIT
1158 .B PTRACE_EVENT_EXIT
1159 will happen before actual death.
1160 This applies to exits via
1163 and signal deaths (except
1165 depending on the kernel version; see BUGS below),
1166 and when threads are torn down on
1168 in a multithreaded process.
1170 The tracer cannot assume that the ptrace-stopped tracee exists.
1171 There are many scenarios when the tracee may die while stopped (such as
1173 Therefore, the tracer must be prepared to handle an
1175 error on any ptrace operation.
1176 Unfortunately, the same error is returned if the tracee
1177 exists but is not ptrace-stopped
1178 (for commands which require a stopped tracee),
1179 or if it is not traced by the process which issued the ptrace call.
1180 The tracer needs to keep track of the stopped/running state of the tracee,
1183 as "tracee died unexpectedly" only if it knows that the tracee has
1184 been observed to enter ptrace-stop.
1185 Note that there is no guarantee that
1187 will reliably report the tracee's death status if a
1188 ptrace operation returned
1191 may return 0 instead.
1192 In other words, the tracee may be "not yet fully dead",
1193 but already refusing ptrace requests.
1195 The tracer can't assume that the tracee
1197 ends its life by reporting
1198 .I WIFEXITED(status)
1200 .IR WIFSIGNALED(status) ;
1201 there are cases where this does not occur.
1202 For example, if a thread other than thread group leader does an
1205 its PID will never be seen again,
1206 and any subsequent ptrace stops will be reported under
1207 the thread group leader's PID.
1209 A tracee can be in two states: running or stopped.
1210 For the purposes of ptrace, a tracee which is blocked in a system call
1215 is nevertheless considered to be running, even if the tracee is blocked
1217 The state of the tracee after
1219 is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
1220 won't work on it, and it will deliver
1223 but it also may be considered "stopped" because
1224 it is not executing instructions (is not scheduled), and if it was
1225 in group-stop before
1227 it will not respond to signals until
1231 There are many kinds of states when the tracee is stopped, and in ptrace
1232 discussions they are often conflated.
1233 Therefore, it is important to use precise terms.
1235 In this manual page, any stopped state in which the tracee is ready
1236 to accept ptrace commands from the tracer is called
1239 be further subdivided into
1240 .IR signal-delivery-stop ,
1243 .IR "PTRACE_EVENT stops" ,
1245 These stopped states are described in detail below.
1247 When the running tracee enters ptrace-stop, it notifies its tracer using
1249 (or one of the other "wait" system calls).
1250 Most of this manual page assumes that the tracer waits with:
1254 pid = waitpid(pid_or_minus_1, &status, __WALL);
1258 Ptrace-stopped tracees are reported as returns with
1261 .I WIFSTOPPED(status)
1264 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
1265 .\" I am not 100% sure there aren't ugly corner cases.) Are the
1266 .\" rules different if user wants to use waitid? Will waitid require
1272 flag does not include the
1276 flags, but implies their functionality.
1282 is not recommended: the "continued" state is per-process and
1283 consuming it can confuse the real parent of the tracee.
1289 to return 0 ("no wait results available yet")
1290 even if the tracer knows there should be a notification.
1296 ptrace(PTRACE_CONT, pid, 0L, 0L);
1297 if (errno == ESRCH) {
1298 /* tracee is dead */
1299 r = waitpid(tracee, &status, __WALL | WNOHANG);
1300 /* r can still be 0 here! */
1305 .\" waitid usage? WNOWAIT?
1306 .\" describe how wait notifications queue (or not queue)
1308 The following kinds of ptrace-stops exist: signal-delivery-stops,
1311 stops, syscall-stops.
1312 They all are reported by
1315 .I WIFSTOPPED(status)
1317 They may be differentiated by examining the value
1319 and if there is ambiguity in that value, by querying
1320 .BR PTRACE_GETSIGINFO .
1323 macro can't be used to perform this examination,
1324 because it returns the value
1325 .IR "(status>>8)\ &\ 0xff" .)
1326 .SS Signal-delivery-stop
1327 When a (possibly multithreaded) process receives any signal except
1329 the kernel selects an arbitrary thread which handles the signal.
1330 (If the signal is generated with
1332 the target thread can be explicitly selected by the caller.)
1333 If the selected thread is traced, it enters signal-delivery-stop.
1334 At this point, the signal is not yet delivered to the process,
1335 and can be suppressed by the tracer.
1336 If the tracer doesn't suppress the signal,
1337 it passes the signal to the tracee in the next ptrace restart request.
1338 This second step of signal delivery is called
1339 .I "signal injection"
1340 in this manual page.
1341 Note that if the signal is blocked,
1342 signal-delivery-stop doesn't happen until the signal is unblocked,
1343 with the usual exception that
1347 Signal-delivery-stop is observed by the tracer as
1350 .I WIFSTOPPED(status)
1351 true, with the signal returned by
1352 .IR WSTOPSIG(status) .
1355 this may be a different kind of ptrace-stop;
1356 see the "Syscall-stops" and "execve" sections below for details.
1359 returns a stopping signal, this may be a group-stop; see below.
1360 .SS Signal injection and suppression
1361 After signal-delivery-stop is observed by the tracer,
1362 the tracer should restart the tracee with the call
1366 ptrace(PTRACE_restart, pid, 0, sig)
1372 is one of the restarting ptrace requests.
1375 is 0, then a signal is not delivered.
1376 Otherwise, the signal
1379 This operation is called
1380 .I "signal injection"
1381 in this manual page, to distinguish it from signal-delivery-stop.
1385 value may be different from the
1387 value: the tracer can cause a different signal to be injected.
1389 Note that a suppressed signal still causes system calls to return
1391 In this case, system calls will be restarted: the tracer will
1392 observe the tracee to reexecute the interrupted system call (or
1393 .BR restart_syscall (2)
1394 system call for a few system calls which use a different mechanism
1395 for restarting) if the tracer uses
1396 .BR PTRACE_SYSCALL .
1397 Even system calls (such as
1399 which are not restartable after signal are restarted after
1400 signal is suppressed;
1401 however, kernel bugs exist which cause some system calls to fail with
1403 even though no observable signal is injected to the tracee.
1405 Restarting ptrace commands issued in ptrace-stops other than
1406 signal-delivery-stop are not guaranteed to inject a signal, even if
1409 No error is reported; a nonzero
1411 may simply be ignored.
1412 Ptrace users should not try to "create a new signal" this way: use
1416 The fact that signal injection requests may be ignored
1417 when restarting the tracee after
1418 ptrace stops that are not signal-delivery-stops
1419 is a cause of confusion among ptrace users.
1420 One typical scenario is that the tracer observes group-stop,
1421 mistakes it for signal-delivery-stop, restarts the tracee with
1425 ptrace(PTRACE_restart, pid, 0, stopsig)
1429 with the intention of injecting
1433 gets ignored and the tracee continues to run.
1437 signal has a side effect of waking up (all threads of)
1438 a group-stopped process.
1439 This side effect happens before signal-delivery-stop.
1440 The tracer can't suppress this side effect (it can
1441 only suppress signal injection, which only causes the
1443 handler to not be executed in the tracee, if such a handler is installed).
1444 In fact, waking up from group-stop may be followed by
1445 signal-delivery-stop for signal(s)
1448 if they were pending when
1453 may be not the first signal observed by the tracee after it was sent.
1455 Stopping signals cause (all threads of) a process to enter group-stop.
1456 This side effect happens after signal injection, and therefore can be
1457 suppressed by the tracer.
1459 In Linux 2.4 and earlier, the
1461 signal can't be injected.
1462 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
1465 .\" /* The debugger continued. Ignore SIGSTOP. */
1466 .\" if (signr == SIGSTOP)
1469 .B PTRACE_GETSIGINFO
1470 can be used to retrieve a
1472 structure which corresponds to the delivered signal.
1473 .B PTRACE_SETSIGINFO
1474 may be used to modify it.
1476 .B PTRACE_SETSIGINFO
1477 has been used to alter
1483 parameter in the restarting command must match,
1484 otherwise the result is undefined.
1486 When a (possibly multithreaded) process receives a stopping signal,
1488 If some threads are traced, they enter a group-stop.
1489 Note that the stopping signal will first cause signal-delivery-stop
1490 (on one tracee only), and only after it is injected by the tracer
1491 (or after it was dispatched to a thread which isn't traced),
1492 will group-stop be initiated on
1494 tracees within the multithreaded process.
1495 As usual, every tracee reports its group-stop separately
1496 to the corresponding tracer.
1498 Group-stop is observed by the tracer as
1501 .I WIFSTOPPED(status)
1502 true, with the stopping signal available via
1503 .IR WSTOPSIG(status) .
1504 The same result is returned by some other classes of ptrace-stops,
1505 therefore the recommended practice is to perform the call
1509 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
1513 The call can be avoided if the signal is not
1519 only these four signals are stopping signals.
1520 If the tracer sees something else, it can't be a group-stop.
1521 Otherwise, the tracer needs to call
1522 .BR PTRACE_GETSIGINFO .
1524 .B PTRACE_GETSIGINFO
1527 then it is definitely a group-stop.
1528 (Other failure codes are possible, such as
1530 ("no such process") if a
1534 If tracee was attached using
1536 group-stop is indicated by
1537 .BR PTRACE_EVENT_STOP :
1538 .IR "status>>16 == PTRACE_EVENT_STOP" .
1539 This allows detection of group-stops
1540 without requiring an extra
1541 .B PTRACE_GETSIGINFO
1545 after the tracer sees the tracee ptrace-stop and until it
1546 restarts or kills it, the tracee will not run,
1547 and will not send notifications (except
1549 death) to the tracer, even if the tracer enters into another
1553 The kernel behavior described in the previous paragraph
1554 causes a problem with transparent handling of stopping signals.
1555 If the tracer restarts the tracee after group-stop,
1557 is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
1558 If the tracer doesn't restart the tracee before entering into the next
1562 signals will not be reported to the tracer;
1563 this would cause the
1565 signals to have no effect on the tracee.
1567 Since Linux 3.4, there is a method to overcome this problem: instead of
1571 command can be used to restart a tracee in a way where it does not execute,
1572 but waits for a new event which it can report via
1575 it is restarted by a
1577 .SS PTRACE_EVENT stops
1580 options, the tracee will enter ptrace-stops called
1585 stops are observed by the tracer as
1588 .IR WIFSTOPPED(status) ,
1594 .BR PTRACE_EVENT_STOP ,
1595 returns the stopping signal if tracee is in a group-stop).
1596 An additional bit is set in the higher byte of the status word:
1603 ((PTRACE_EVENT_foo<<8) | SIGTRAP).
1607 The following events exist:
1609 .B PTRACE_EVENT_VFORK
1610 Stop before return from
1617 When the tracee is continued after this stop, it will wait for child to
1618 exit/exec before continuing its execution
1619 (in other words, the usual behavior on
1622 .B PTRACE_EVENT_FORK
1623 Stop before return from
1627 with the exit signal set to
1630 .B PTRACE_EVENT_CLONE
1631 Stop before return from
1634 .B PTRACE_EVENT_VFORK_DONE
1635 Stop before return from
1642 but after the child unblocked this tracee by exiting or execing.
1644 For all four stops described above,
1645 the stop occurs in the parent (i.e., the tracee),
1646 not in the newly created thread.
1647 .B PTRACE_GETEVENTMSG
1648 can be used to retrieve the new thread's ID.
1650 .B PTRACE_EVENT_EXEC
1651 Stop before return from
1654 .B PTRACE_GETEVENTMSG
1655 returns the former thread ID.
1657 .B PTRACE_EVENT_EXIT
1658 Stop before exit (including death from
1659 .BR exit_group (2)),
1660 signal death, or exit caused by
1662 in a multithreaded process.
1663 .B PTRACE_GETEVENTMSG
1664 returns the exit status.
1665 Registers can be examined
1666 (unlike when "real" exit happens).
1667 The tracee is still alive; it needs to be
1670 .BR PTRACE_DETACH ed
1673 .B PTRACE_EVENT_STOP
1676 command, or group-stop, or initial ptrace-stop when a new child is attached
1677 (only if attached using
1680 .B PTRACE_EVENT_SECCOMP
1683 rule on tracee syscall entry when
1684 .B PTRACE_O_TRACESECCOMP
1685 has been set by the tracer.
1686 The seccomp event message data (from the
1688 portion of the seccomp filter rule) can be retrieved with
1689 .BR PTRACE_GETEVENTMSG .
1690 The semantics of this stop are described in
1691 detail in a separate section below.
1693 .B PTRACE_GETSIGINFO
1703 .IR "(event<<8)\ |\ SIGTRAP" .
1705 If the tracee was restarted by
1710 syscall-enter-stop just prior to entering any system call (which
1711 will not be executed if the restart was using
1713 regardless of any change made to registers at this point or how the
1714 tracee is restarted after this stop).
1715 No matter which method caused the syscall-entry-stop,
1716 if the tracer restarts the tracee with
1717 .BR PTRACE_SYSCALL ,
1718 the tracee enters syscall-exit-stop when the system call is finished,
1719 or if it is interrupted by a signal.
1720 (That is, signal-delivery-stop never happens between syscall-enter-stop
1721 and syscall-exit-stop; it happens
1723 syscall-exit-stop.).
1724 If the tracee is continued using any other method (including
1725 .BR PTRACE_SYSEMU ),
1726 no syscall-exit-stop occurs.
1727 Note that all mentions
1730 .BR PTRACE_SYSEMU_SINGLESTEP .
1732 However, even if the tracee was continued using
1733 .BR PTRACE_SYSCALL ,
1734 it is not guaranteed that the next stop will be a syscall-exit-stop.
1735 Other possibilities are that the tracee may stop in a
1737 stop (including seccomp stops), exit (if it entered
1740 .BR exit_group (2)),
1743 or die silently (if it is a thread group leader, the
1745 happened in another thread,
1746 and that thread is not traced by the same tracer;
1747 this situation is discussed later).
1749 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1752 .I WIFSTOPPED(status)
1758 .B PTRACE_O_TRACESYSGOOD
1759 option was set by the tracer, then
1762 .IR "(SIGTRAP\ |\ 0x80)" .
1764 Syscall-stops can be distinguished from signal-delivery-stop with
1767 .B PTRACE_GETSIGINFO
1768 for the following cases:
1772 was delivered as a result of a user-space action,
1773 for example, a system call
1778 expiration of a POSIX timer,
1779 change of state on a POSIX message queue,
1780 or completion of an asynchronous I/O request.
1782 .IR si_code " == SI_KERNEL (0x80)"
1784 was sent by the kernel.
1786 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1787 This is a syscall-stop.
1789 However, syscall-stops happen very often (twice per system call),
1791 .B PTRACE_GETSIGINFO
1792 for every syscall-stop may be somewhat expensive.
1794 Some architectures allow the cases to be distinguished
1795 by examining registers.
1796 For example, on x86,
1800 in syscall-enter-stop.
1803 (like any other signal) always happens
1808 almost never contains
1812 looks like "syscall-stop which is not syscall-enter-stop";
1813 in other words, it looks like a
1814 "stray syscall-exit-stop" and can be detected this way.
1815 But such detection is fragile and is best avoided.
1818 .B PTRACE_O_TRACESYSGOOD
1819 option is the recommended method to distinguish syscall-stops
1820 from other kinds of ptrace-stops,
1821 since it is reliable and does not incur a performance penalty.
1823 Syscall-enter-stop and syscall-exit-stop are
1824 indistinguishable from each other by the tracer.
1825 The tracer needs to keep track of the sequence of
1826 ptrace-stops in order to not misinterpret syscall-enter-stop as
1827 syscall-exit-stop or vice versa.
1828 In general, a syscall-enter-stop is
1829 always followed by syscall-exit-stop,
1831 stop, or the tracee's death;
1832 no other kinds of ptrace-stop can occur in between.
1833 However, note that seccomp stops (see below) can cause syscall-exit-stops,
1834 without preceding syscall-entry-stops.
1835 If seccomp is in use, care needs
1836 to be taken not to misinterpret such stops as syscall-entry-stops.
1838 If after syscall-enter-stop,
1839 the tracer uses a restarting command other than
1840 .BR PTRACE_SYSCALL ,
1841 syscall-exit-stop is not generated.
1843 .B PTRACE_GETSIGINFO
1844 on syscall-stops returns
1853 .IR (SIGTRAP|0x80) .
1855 .SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to 4.7)
1857 .B PTRACE_EVENT_SECCOMP
1858 stops and their interaction with other kinds
1859 of ptrace stops has changed between kernel versions.
1860 This documents the behavior
1861 from their introduction until Linux 4.7 (inclusive).
1862 The behavior in later kernel versions is documented in the next section.
1865 .B PTRACE_EVENT_SECCOMP
1866 stop occurs whenever a
1867 .B SECCOMP_RET_TRACE
1869 This is independent of which methods was used to restart the system call.
1870 Notably, seccomp still runs even if the tracee was restarted using
1872 and this system call is unconditionally skipped.
1874 Restarts from this stop will behave as if the stop had occurred right
1875 before the system call in question.
1880 will normally cause a subsequent syscall-entry-stop.
1881 However, if after the
1882 .B PTRACE_EVENT_SECCOMP
1883 the system call number is negative,
1884 both the syscall-entry-stop and the system call itself will be skipped.
1885 This means that if the system call number is negative after a
1886 .B PTRACE_EVENT_SECCOMP
1887 and the tracee is restarted using
1888 .BR PTRACE_SYSCALL ,
1889 the next observed stop will be a syscall-exit-stop,
1890 rather than the syscall-entry-stop that might have been expected.
1892 .SS PTRACE_EVENT_SECCOMP stops (since Linux 4.8)
1893 Starting with Linux 4.8,
1894 .\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea
1896 .B PTRACE_EVENT_SECCOMP
1897 stop was reordered to occur between syscall-entry-stop and
1899 Note that seccomp no longer runs (and no
1900 .B PTRACE_EVENT_SECCOMP
1901 will be reported) if the system call is skipped due to
1905 .B PTRACE_EVENT_SECCOMP
1906 stop functions comparably
1907 to a syscall-entry-stop (i.e., continuations using
1909 will cause syscall-exit-stops,
1910 the system call number may be changed and any other modified registers
1911 are visible to the to-be-executed system call as well).
1912 Note that there may be,
1913 but need not have been a preceding syscall-entry-stop.
1916 .B PTRACE_EVENT_SECCOMP
1917 stop, seccomp will be rerun, with a
1918 .B SECCOMP_RET_TRACE
1919 rule now functioning the same as a
1920 .BR SECCOMP_RET_ALLOW .
1921 Specifically, this means that if registers are not modified during the
1922 .B PTRACE_EVENT_SECCOMP
1923 stop, the system call will then be allowed.
1925 .SS PTRACE_SINGLESTEP stops
1926 [Details of these kinds of stops are yet to be documented.]
1929 .\" document stops occurring with PTRACE_SINGLESTEP
1931 .SS Informational and restarting ptrace commands
1932 Most ptrace commands (all except
1935 .BR PTRACE_TRACEME ,
1936 .BR PTRACE_INTERRUPT ,
1939 require the tracee to be in a ptrace-stop, otherwise they fail with
1942 When the tracee is in ptrace-stop,
1943 the tracer can read and write data to
1944 the tracee using informational commands.
1945 These commands leave the tracee in ptrace-stopped state:
1949 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1950 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1951 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1952 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1953 ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
1954 ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
1955 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1956 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1957 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
1958 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1962 Note that some errors are not reported.
1963 For example, setting signal information
1965 may have no effect in some ptrace-stops, yet the call may succeed
1966 (return 0 and not set
1969 .B PTRACE_GETEVENTMSG
1970 may succeed and return some random value if current ptrace-stop
1971 is not documented as returning a meaningful event message.
1977 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1982 The tracee's current flags are replaced.
1983 Flags are inherited by new tracees created and "auto-attached" via active
1984 .BR PTRACE_O_TRACEFORK ,
1985 .BR PTRACE_O_TRACEVFORK ,
1987 .B PTRACE_O_TRACECLONE
1990 Another group of commands makes the ptrace-stopped tracee run.
1995 ptrace(cmd, pid, 0, sig);
2005 .BR PTRACE_SYSCALL ,
2006 .BR PTRACE_SINGLESTEP ,
2009 .BR PTRACE_SYSEMU_SINGLESTEP .
2010 If the tracee is in signal-delivery-stop,
2012 is the signal to be injected (if it is nonzero).
2016 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
2017 recommended practice is to always pass 0 in
2019 .SS Attaching and detaching
2020 A thread can be attached to the tracer using the call
2024 ptrace(PTRACE_ATTACH, pid, 0, 0);
2032 ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
2040 If the tracer wants this
2042 to have no effect, it needs to suppress it.
2043 Note that if other signals are concurrently sent to
2044 this thread during attach,
2045 the tracer may see the tracee enter signal-delivery-stop
2046 with other signal(s) first!
2047 The usual practice is to reinject these signals until
2049 is seen, then suppress
2052 The design bug here is that a ptrace attach and a concurrently delivered
2054 may race and the concurrent
2058 .\" FIXME Describe how to attach to a thread which is already group-stopped.
2060 Since attaching sends
2062 and the tracer usually suppresses it, this may cause a stray
2064 return from the currently executing system call in the tracee,
2065 as described in the "Signal injection and suppression" section.
2069 can be used instead of
2072 does not stop the attached process.
2074 it after attach (or at any other time) without sending it any signals,
2083 ptrace(PTRACE_TRACEME, 0, 0, 0);
2087 turns the calling thread into a tracee.
2088 The thread continues to run (doesn't enter ptrace-stop).
2089 A common practice is to follow the
2099 and allow the parent (which is our tracer now) to observe our
2100 signal-delivery-stop.
2103 .BR PTRACE_O_TRACEFORK ,
2104 .BR PTRACE_O_TRACEVFORK ,
2106 .B PTRACE_O_TRACECLONE
2107 options are in effect, then children created by, respectively,
2117 with the exit signal set to
2121 are automatically attached to the same tracer which traced their parent.
2123 is delivered to the children, causing them to enter
2124 signal-delivery-stop after they exit the system call which created them.
2126 Detaching of the tracee is performed by:
2130 ptrace(PTRACE_DETACH, pid, 0, sig);
2135 is a restarting operation;
2136 therefore it requires the tracee to be in ptrace-stop.
2137 If the tracee is in signal-delivery-stop, a signal can be injected.
2140 parameter may be silently ignored.
2142 If the tracee is running when the tracer wants to detach it,
2143 the usual solution is to send
2147 to make sure it goes to the correct thread),
2148 wait for the tracee to stop in signal-delivery-stop for
2150 and then detach it (suppressing
2153 A design bug is that this can race with concurrent
2155 Another complication is that the tracee may enter other ptrace-stops
2156 and needs to be restarted and waited for again, until
2159 Yet another complication is to be sure that
2160 the tracee is not already ptrace-stopped,
2161 because no signal delivery happens while it is\(emnot even
2163 .\" FIXME Describe how to detach from a group-stopped tracee so that it
2164 .\" doesn't run, but continues to wait for SIGCONT.
2166 If the tracer dies, all tracees are automatically detached and restarted,
2167 unless they were in group-stop.
2168 Handling of restart from group-stop is currently buggy,
2169 but the "as planned" behavior is to leave tracee stopped and waiting for
2171 If the tracee is restarted from signal-delivery-stop,
2172 the pending signal is injected.
2173 .SS execve(2) under ptrace
2174 .\" clone(2) CLONE_THREAD says:
2175 .\" If any of the threads in a thread group performs an execve(2),
2176 .\" then all threads other than the thread group leader are terminated,
2177 .\" and the new program is executed in the thread group leader.
2179 When one thread in a multithreaded process calls
2181 the kernel destroys all other threads in the process,
2182 .\" In kernel 3.1 sources, see fs/exec.c::de_thread()
2183 and resets the thread ID of the execing thread to the
2184 thread group ID (process ID).
2185 (Or, to put things another way, when a multithreaded process does an
2187 at completion of the call, it appears as though the
2189 occurred in the thread group leader, regardless of which thread did the
2191 This resetting of the thread ID looks very confusing to tracers:
2193 All other threads stop in
2194 .B PTRACE_EVENT_EXIT
2196 .B PTRACE_O_TRACEEXIT
2197 option was turned on.
2198 Then all other threads except the thread group leader report
2199 death as if they exited via
2203 The execing tracee changes its thread ID while it is in the
2205 (Remember, under ptrace, the "pid" returned from
2207 or fed into ptrace calls, is the tracee's thread ID.)
2208 That is, the tracee's thread ID is reset to be the same as its process ID,
2209 which is the same as the thread group leader's thread ID.
2212 .B PTRACE_EVENT_EXEC
2213 stop happens, if the
2214 .B PTRACE_O_TRACEEXEC
2215 option was turned on.
2217 If the thread group leader has reported its
2218 .B PTRACE_EVENT_EXIT
2220 it appears to the tracer that
2221 the dead thread leader "reappears from nowhere".
2222 (Note: the thread group leader does not report death via
2223 .I WIFEXITED(status)
2224 until there is at least one other live thread.
2225 This eliminates the possibility that the tracer will see
2226 it dying and then reappearing.)
2227 If the thread group leader was still alive,
2228 for the tracer this may look as if thread group leader
2229 returns from a different system call than it entered,
2230 or even "returned from a system call even though
2231 it was not in any system call".
2232 If the thread group leader was not traced
2233 (or was traced by a different tracer), then during
2235 it will appear as if it has become a tracee of
2236 the tracer of the execing tracee.
2238 All of the above effects are the artifacts of
2239 the thread ID change in the tracee.
2242 .B PTRACE_O_TRACEEXEC
2243 option is the recommended tool for dealing with this situation.
2245 .B PTRACE_EVENT_EXEC
2250 In this stop, the tracer can use
2251 .B PTRACE_GETEVENTMSG
2252 to retrieve the tracee's former thread ID.
2253 (This feature was introduced in Linux 3.0.)
2255 .B PTRACE_O_TRACEEXEC
2256 option disables legacy
2261 When the tracer receives
2262 .B PTRACE_EVENT_EXEC
2264 it is guaranteed that except this tracee and the thread group leader,
2265 no other threads from the process are alive.
2268 .B PTRACE_EVENT_EXEC
2270 the tracer should clean up all its internal
2271 data structures describing the threads of this process,
2272 and retain only one data structure\(emone which
2273 describes the single still running tracee, with
2277 thread ID == thread group ID == process ID.
2281 Example: two threads call
2286 *** we get syscall-enter-stop in thread 1: **
2287 PID1 execve("/bin/foo", "foo" <unfinished ...>
2288 *** we issue PTRACE_SYSCALL for thread 1 **
2289 *** we get syscall-enter-stop in thread 2: **
2290 PID2 execve("/bin/bar", "bar" <unfinished ...>
2291 *** we issue PTRACE_SYSCALL for thread 2 **
2292 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
2293 *** we get syscall-exit-stop for PID0: **
2294 PID0 <... execve resumed> ) = 0
2298 .B PTRACE_O_TRACEEXEC
2301 in effect for the execing tracee,
2302 and if the tracee was
2303 .BR PTRACE_ATTACH ed
2306 the kernel delivers an extra
2311 This is an ordinary signal (similar to one which can be
2313 .IR "kill \-TRAP" ),
2314 not a special kind of ptrace-stop.
2316 .B PTRACE_GETSIGINFO
2317 for this signal returns
2321 This signal may be blocked by signal mask,
2322 and thus may be delivered (much) later.
2324 Usually, the tracer (for example,
2326 would not want to show this extra post-execve
2328 signal to the user, and would suppress its delivery to the tracee (if
2332 it is a killing signal).
2333 However, determining
2336 to suppress is not easy.
2338 .B PTRACE_O_TRACEEXEC
2341 and thus suppressing this extra
2343 is the recommended approach.
2345 The ptrace API (ab)uses the standard UNIX parent/child signaling over
2347 This used to cause the real parent of the process to stop receiving
2350 notifications when the child process is traced by some other process.
2352 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
2353 exist; see BUGS below.
2355 As of Linux 2.6.38, the following is believed to work correctly:
2357 exit/death by signal is reported first to the tracer, then,
2358 when the tracer consumes the
2360 result, to the real parent (to the real parent only when the
2361 whole multithreaded process exits).
2362 If the tracer and the real parent are the same process,
2363 the report is sent only once.
2367 requests return the requested data (but see NOTES),
2369 .B PTRACE_SECCOMP_GET_FILTER
2370 request returns the number of instructions in the BPF program,
2372 .B PTRACE_GET_SYSCALL_INFO
2373 request returns the number of bytes available to be written by the kernel,
2374 and other requests return zero.
2376 On error, all requests return \-1, and
2378 is set to indicate the error.
2379 Since the value returned by a successful
2381 request may be \-1, the caller must clear
2383 before the call, and then check it afterward
2384 to determine whether or not an error occurred.
2388 (i386 only) There was an error with allocating or freeing a debug register.
2391 There was an attempt to read from or write to an invalid area in
2392 the tracer's or the tracee's memory,
2393 probably because the area wasn't mapped or accessible.
2394 Unfortunately, under Linux, different variations of this fault
2399 more or less arbitrarily.
2402 An attempt was made to set an invalid option.
2406 is invalid, or an attempt was made to read from or
2407 write to an invalid area in the tracer's or the tracee's memory,
2408 or there was a word-alignment violation,
2409 or an invalid signal was specified during a restart request.
2412 The specified process cannot be traced.
2413 This could be because the
2414 tracer has insufficient privileges (the required capability is
2415 .BR CAP_SYS_PTRACE );
2416 unprivileged processes cannot trace processes that they
2417 cannot send signals to or those running
2418 set-user-ID/set-group-ID programs, for obvious reasons.
2419 Alternatively, the process may already be being traced,
2420 or (on kernels before 2.6.26) be
2425 The specified process does not exist, or is not currently being traced
2426 by the caller, or is not stopped
2427 (for requests that require a stopped tracee).
2431 Although arguments to
2433 are interpreted according to the prototype given,
2434 glibc currently declares
2436 as a variadic function with only the
2439 It is recommended to always supply four arguments,
2440 even if the requested operation does not use them,
2441 setting unused/ignored arguments to
2446 In Linux kernels before 2.6.26,
2447 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
2449 the process with PID 1, may not be traced.
2451 A tracees parent continues to be the tracer even if that tracer calls
2454 The layout of the contents of memory and the USER area are
2455 quite operating-system- and architecture-specific.
2456 The offset supplied, and the data returned,
2457 might not entirely match with the definition of
2459 .\" See http://lkml.org/lkml/2008/5/8/375
2461 The size of a "word" is determined by the operating-system variant
2462 (e.g., for 32-bit Linux it is 32 bits).
2464 This page documents the way the
2466 call works currently in Linux.
2467 Its behavior differs significantly on other flavors of UNIX.
2470 is highly specific to the operating system and architecture.
2472 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2474 .SS Ptrace access mode checking
2475 Various parts of the kernel-user-space API (not just
2477 operations), require so-called "ptrace access mode" checks,
2478 whose outcome determines whether an operation is permitted
2479 (or, in a few cases, causes a "read" operation to return sanitized data).
2480 These checks are performed in cases where one process can
2481 inspect sensitive information about,
2482 or in some cases modify the state of, another process.
2483 The checks are based on factors such as the credentials and capabilities
2484 of the two processes,
2485 whether or not the "target" process is dumpable,
2486 and the results of checks performed by any enabled Linux Security Module
2487 (LSM)\(emfor example, SELinux, Yama, or Smack\(emand by the commoncap LSM
2488 (which is always invoked).
2490 Prior to Linux 2.6.27, all access checks were of a single type.
2492 .\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd
2493 two access mode levels are distinguished:
2496 For "read" operations or other operations that are less dangerous,
2498 .BR get_robust_list (2);
2501 .IR /proc/ pid /auxv ,
2502 .IR /proc/ pid /environ ,
2504 .IR /proc/ pid /stat ;
2508 .IR /proc/ pid /ns/*
2511 .B PTRACE_MODE_ATTACH
2512 For "write" operations, or other operations that are more dangerous,
2513 such as: ptrace attaching
2514 .RB ( PTRACE_ATTACH )
2517 .BR process_vm_writev (2).
2518 .RB ( PTRACE_MODE_ATTACH
2519 was effectively the default before Linux 2.6.27.)
2521 .\" Regarding the above description of the distinction between
2522 .\" PTRACE_MODE_READ and PTRACE_MODE_ATTACH, Stephen Smalley notes:
2524 .\" That was the intent when the distinction was introduced, but it doesn't
2525 .\" appear to have been properly maintained, e.g. there is now a common
2526 .\" helper lock_trace() that is used for
2527 .\" /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and
2528 .\" PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show(). Likely
2529 .\" should review and make them consistent. There was also some debate
2530 .\" about proper handling of /proc/pid/fd. Arguably that one might belong
2531 .\" back in the _ATTACH camp.
2535 .\" commit caaee6234d05a58c5b4d05e7bf766131b810a657
2536 the above access mode checks are combined (ORed) with
2537 one of the following modifiers:
2539 .B PTRACE_MODE_FSCREDS
2540 Use the caller's filesystem UID and GID (see
2541 .BR credentials (7))
2542 or effective capabilities for LSM checks.
2544 .B PTRACE_MODE_REALCREDS
2545 Use the caller's real UID and GID or permitted capabilities for LSM checks.
2546 This was effectively the default before Linux 4.5.
2548 Because combining one of the credential modifiers with one of
2549 the aforementioned access modes is typical,
2550 some macros are defined in the kernel sources for the combinations:
2552 .B PTRACE_MODE_READ_FSCREDS
2554 .BR "PTRACE_MODE_READ | PTRACE_MODE_FSCREDS" .
2556 .B PTRACE_MODE_READ_REALCREDS
2558 .BR "PTRACE_MODE_READ | PTRACE_MODE_REALCREDS" .
2560 .B PTRACE_MODE_ATTACH_FSCREDS
2562 .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS" .
2564 .B PTRACE_MODE_ATTACH_REALCREDS
2566 .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" .
2568 One further modifier can be ORed with the access mode:
2570 .BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)"
2571 .\" commit 69f594a38967f4540ce7a29b3fd214e68a8330bd
2572 .\" Just for /proc/pid/stat
2573 Don't audit this access mode check.
2574 This modifier is employed for ptrace access mode checks
2575 (such as checks when reading
2576 .IR /proc/ pid /stat )
2577 that merely cause the output to be filtered or sanitized,
2578 rather than causing an error to be returned to the caller.
2579 In these cases, accessing the file is not a security violation and
2580 there is no reason to generate a security audit record.
2581 This modifier suppresses the generation of
2582 such an audit record for the particular access check.
2584 Note that all of the
2586 constants described in this subsection are kernel-internal,
2587 and not visible to user space.
2588 The constant names are mentioned here in order to label the various kinds of
2589 ptrace access mode checks that are performed for various system calls
2590 and accesses to various pseudofiles (e.g., under
2592 These names are used in other manual pages to provide a simple
2593 shorthand for labeling the different kernel checks.
2595 The algorithm employed for ptrace access mode checking determines whether
2596 the calling process is allowed to perform the corresponding action
2597 on the target process.
2598 (In the case of opening
2600 files, the "calling process" is the one opening the file,
2601 and the process with the corresponding PID is the "target process".)
2602 The algorithm is as follows:
2604 If the calling thread and the target thread are in the same
2605 thread group, access is always allowed.
2607 If the access mode specifies
2608 .BR PTRACE_MODE_FSCREDS ,
2609 then, for the check in the next step,
2610 employ the caller's filesystem UID and GID.
2612 .BR credentials (7),
2613 the filesystem UID and GID almost always have the same values
2614 as the corresponding effective IDs.)
2616 Otherwise, the access mode specifies
2617 .BR PTRACE_MODE_REALCREDS ,
2618 so use the caller's real UID and GID for the checks in the next step.
2619 (Most APIs that check the caller's UID and GID use the effective IDs.
2620 For historical reasons, the
2621 .B PTRACE_MODE_REALCREDS
2622 check uses the real IDs instead.)
2626 of the following is true:
2629 The real, effective, and saved-set user IDs of the target
2630 match the caller's user ID,
2632 the real, effective, and saved-set group IDs of the target
2633 match the caller's group ID.
2637 capability in the user namespace of the target.
2640 Deny access if the target process "dumpable" attribute has a value other than 1
2641 .RB ( SUID_DUMP_USER ;
2642 see the discussion of
2646 and the caller does not have the
2648 capability in the user namespace of the target process.
2651 .IR security_ptrace_access_check ()
2652 interface is invoked to see if ptrace access is permitted.
2653 The results depend on the LSM(s).
2654 The implementation of this interface in the commoncap LSM performs
2655 the following steps:
2656 .\" (in cap_ptrace_access_check()):
2659 If the access mode includes
2660 .BR PTRACE_MODE_FSCREDS ,
2661 then use the caller's
2664 in the following check;
2665 otherwise (the access mode specifies
2666 .BR PTRACE_MODE_REALCREDS ,
2667 so) use the caller's
2673 of the following is true:
2676 The caller and the target process are in the same user namespace,
2677 and the caller's capabilities are a superset of the target process's
2683 capability in the target process's user namespace.
2686 Note that the commoncap LSM does not distinguish between
2689 .BR PTRACE_MODE_ATTACH .
2692 If access has not been denied by any of the preceding steps,
2693 then access is allowed.
2695 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2697 .SS /proc/sys/kernel/yama/ptrace_scope
2698 On systems with the Yama Linux Security Module (LSM) installed
2699 (i.e., the kernel was configured with
2700 .BR CONFIG_SECURITY_YAMA ),
2702 .I /proc/sys/kernel/yama/ptrace_scope
2703 file (available since Linux 3.4)
2704 .\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
2705 can be used to restrict the ability to trace a process with
2707 (and thus also the ability to use tools such as
2711 The goal of such restrictions is to prevent attack escalation whereby
2712 a compromised process can ptrace-attach to other sensitive processes
2713 (e.g., a GPG agent or an SSH session) owned by the user in order
2714 to gain additional credentials that may exist in memory
2715 and thus expand the scope of the attack.
2717 More precisely, the Yama LSM limits two types of operations:
2719 Any operation that performs a ptrace access mode
2720 .B PTRACE_MODE_ATTACH
2721 check\(emfor example,
2724 (See the "Ptrace access mode checking" discussion above.)
2727 .BR PTRACE_TRACEME .
2729 A process that has the
2731 capability can update the
2732 .I /proc/sys/kernel/yama/ptrace_scope
2733 file with one of the following values:
2735 0 ("classic ptrace permissions")
2736 No additional restrictions on operations that perform
2737 .B PTRACE_MODE_ATTACH
2738 checks (beyond those imposed by the commoncap and other LSMs).
2744 1 ("restricted ptrace") [default value]
2745 When performing an operation that requires a
2746 .B PTRACE_MODE_ATTACH
2747 check, the calling process must either have the
2749 capability in the user namespace of the target process or
2750 it must have a predefined relationship with the target process.
2752 the predefined relationship is that the target process
2753 must be a descendant of the caller.
2755 A target process can employ the
2758 operation to declare an additional PID that is allowed to perform
2759 .B PTRACE_MODE_ATTACH
2760 operations on the target.
2761 See the kernel source file
2762 .I Documentation/admin\-guide/LSM/Yama.rst
2763 .\" commit 90bb766440f2147486a2acc3e793d7b8348b0c22
2765 .I Documentation/security/Yama.txt
2767 for further details.
2773 2 ("admin-only attach")
2774 Only processes with the
2776 capability in the user namespace of the target process may perform
2777 .B PTRACE_MODE_ATTACH
2778 operations or trace children that employ
2779 .BR PTRACE_TRACEME .
2782 No process may perform
2783 .B PTRACE_MODE_ATTACH
2784 operations or trace children that employ
2785 .BR PTRACE_TRACEME .
2787 Once this value has been written to the file, it cannot be changed.
2789 With respect to values 1 and 2,
2790 note that creating a new user namespace effectively removes the
2791 protection offered by Yama.
2792 This is because a process in the parent user namespace whose effective
2793 UID matches the UID of the creator of a child namespace
2794 has all capabilities (including
2795 .BR CAP_SYS_PTRACE )
2796 when performing operations within the child user namespace
2797 (and further-removed descendants of that namespace).
2798 Consequently, when a process tries to use user namespaces to sandbox itself,
2799 it inadvertently weakens the protections offered by the Yama LSM.
2801 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2803 .SS C library/kernel differences
2804 At the system call level, the
2805 .BR PTRACE_PEEKTEXT ,
2806 .BR PTRACE_PEEKDATA ,
2809 requests have a different API: they store the result
2810 at the address specified by the
2812 parameter, and the return value is the error flag.
2813 The glibc wrapper function provides the API given in DESCRIPTION above,
2814 with the result being returned via the function return value.
2816 On hosts with 2.6 kernel headers,
2817 .B PTRACE_SETOPTIONS
2818 is declared with a different value than the one for 2.4.
2819 This leads to applications compiled with 2.6 kernel
2820 headers failing when run on 2.4 kernels.
2821 This can be worked around by redefining
2822 .B PTRACE_SETOPTIONS
2824 .BR PTRACE_OLDSETOPTIONS ,
2827 Group-stop notifications are sent to the tracer, but not to real parent.
2828 Last confirmed on 2.6.38.6.
2830 If a thread group leader is traced and exits by calling
2832 .\" Note from Denys Vlasenko:
2833 .\" Here "exits" means any kind of death - _exit, exit_group,
2834 .\" signal death. Signal death and exit_group cases are trivial,
2835 .\" though: since signal death and exit_group kill all other threads
2836 .\" too, "until all other threads exit" thing happens rather soon
2837 .\" in these cases. Therefore, only _exit presents observably
2838 .\" puzzling behavior to ptrace users: thread leader _exit's,
2839 .\" but WIFEXITED isn't reported! We are trying to explain here
2842 .B PTRACE_EVENT_EXIT
2843 stop will happen for it (if requested), but the subsequent
2845 notification will not be delivered until all other threads exit.
2846 As explained above, if one of other threads calls
2848 the death of the thread group leader will
2851 If the execed thread is not traced by this tracer,
2852 the tracer will never know that
2855 One possible workaround is to
2857 the thread group leader instead of restarting it in this case.
2858 Last confirmed on 2.6.38.6.
2859 .\" FIXME . need to test/verify this scenario
2863 signal may still cause a
2864 .B PTRACE_EVENT_EXIT
2865 stop before actual signal death.
2866 This may be changed in the future;
2868 is meant to always immediately kill tasks even under ptrace.
2869 Last confirmed on Linux 3.13.
2871 Some system calls return with
2873 if a signal was sent to a tracee, but delivery was suppressed by the tracer.
2874 (This is very typical operation: it is usually
2875 done by debuggers on every attach, in order to not introduce
2878 As of Linux 3.2.9, the following system calls are affected
2879 (this list is likely incomplete):
2886 The usual symptom of this bug is that when you attach to
2887 a quiescent process with the command
2891 strace \-p <process\-ID>
2895 then, instead of the usual
2896 and expected one-line output such as
2900 restart_syscall(<... resuming interrupted call ...>_
2908 select(6, [5], NULL, [5], NULL_
2912 ('_' denotes the cursor position), you observe more than one line.
2917 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
2922 What is not visible here is that the process was blocked in
2929 to return to user space with the error
2931 In this particular case, the program reacted to
2933 by checking the current time, and then executing
2936 (Programs which do not expect such "stray"
2938 errors may behave in an unintended way upon an
2942 Contrary to the normal rules, the glibc wrapper for
2962 .BR capabilities (7),