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 2020-02-09 "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
469 signal to the 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.
590 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
591 Stop the tracee at the next
593 and automatically start tracing the newly vforked process,
594 which will start with a
603 by the tracer will return a
608 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
611 The PID of the new process can be retrieved with
612 .BR PTRACE_GETEVENTMSG .
614 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
615 Stop the tracee at the completion of the next
619 by the tracer will return a
624 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
627 The PID of the new process can (since Linux 2.6.18) be retrieved with
628 .BR PTRACE_GETEVENTMSG .
630 .BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)"
631 Stop the tracee when a
633 .BR SECCOMP_RET_TRACE
637 by the tracer will return a
642 status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))
645 While this triggers a
647 stop, it is similar to a syscall-enter-stop.
648 For details, see the note on
649 .B PTRACE_EVENT_SECCOMP
651 The seccomp event message data (from the
653 portion of the seccomp filter rule) can be retrieved with
654 .BR PTRACE_GETEVENTMSG .
656 .BR PTRACE_O_SUSPEND_SECCOMP " (since Linux 4.3)"
657 .\" commit 13c4a90119d28cfcb6b5bdd820c233b86c2b0237
658 Suspend the tracee's seccomp protections.
659 This applies regardless of mode, and
660 can be used when the tracee has not yet installed seccomp filters.
661 That is, a valid use case is to suspend a tracee's seccomp protections
662 before they are installed by the tracee,
663 let the tracee install the filters,
664 and then clear this flag when the filters should be resumed.
665 Setting this option requires that the tracer have the
668 not have any seccomp protections installed, and not have
669 .BR PTRACE_O_SUSPEND_SECCOMP
673 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
674 Retrieve a message (as an
675 .IR "unsigned long" )
676 about the ptrace event
677 that just happened, placing it at the address
681 .BR PTRACE_EVENT_EXIT ,
682 this is the tracee's exit status.
684 .BR PTRACE_EVENT_FORK ,
685 .BR PTRACE_EVENT_VFORK ,
686 .BR PTRACE_EVENT_VFORK_DONE ,
688 .BR PTRACE_EVENT_CLONE ,
689 this is the PID of the new process.
691 .BR PTRACE_EVENT_SECCOMP ,
696 associated with the triggered rule.
701 Restart the stopped tracee process.
705 it is interpreted as the number of a signal to be delivered to the tracee;
706 otherwise, no signal is delivered.
707 Thus, for example, the tracer can control
708 whether a signal sent to the tracee is delivered or not.
712 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
713 Restart the stopped tracee as for
715 but arrange for the tracee to be stopped at
716 the next entry to or exit from a system call,
717 or after execution of a single instruction, respectively.
718 (The tracee will also, as usual, be stopped upon receipt of a signal.)
719 From the tracer's perspective, the tracee will appear to have been
720 stopped by receipt of a
724 for example, the idea is to inspect
725 the arguments to the system call at the first stop,
728 and inspect the return value of the system call at the second stop.
731 argument is treated as for
736 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
739 continue and stop on entry to the next system call,
740 which will not be executed.
741 See the documentation on syscall-stops below.
743 .BR PTRACE_SYSEMU_SINGLESTEP ,
744 do the same but also singlestep if not a system call.
745 This call is used by programs like
746 User Mode Linux that want to emulate all the tracee's system calls.
749 argument is treated as for
754 These requests are currently
756 supported only on x86.
758 .BR PTRACE_LISTEN " (since Linux 3.4)"
759 Restart the stopped tracee, but prevent it from executing.
760 The resulting state of the tracee is similar to a process which
761 has been stopped by a
763 (or other stopping signal).
764 See the "group-stop" subsection for additional information.
766 works only on tracees attached by
778 .I This operation is deprecated; do not use it!
787 is that it requires the tracee to be in signal-delivery-stop,
788 otherwise it may not work
789 (i.e., may complete successfully but won't kill the tracee).
790 By contrast, sending a
792 directly has no such limitation.
793 .\" [Note from Denys Vlasenko:
794 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
795 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
797 .BR PTRACE_INTERRUPT " (since Linux 3.4)"
799 If the tracee is running or sleeping in kernel space and
802 the system call is interrupted and syscall-exit-stop is reported.
803 (The interrupted system call is restarted when the tracee is restarted.)
804 If the tracee was already stopped by a signal and
807 the tracee stops with
811 returns the stop signal.
812 If any other ptrace-stop is generated at the same time (for example,
813 if a signal is sent to the tracee), this ptrace-stop happens.
814 If none of the above applies (for example, if the tracee is running in user
815 space), it stops with
822 only works on tracees attached by
826 Attach to the process specified in
828 making it a tracee of the calling process.
829 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
830 .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
831 .\" Basically, it's not true for any Linux in practical use.
832 .\" ; the behavior of the tracee is as if it had done a
833 .\" .BR PTRACE_TRACEME .
834 .\" The calling process actually becomes the parent of the tracee
835 .\" process for most purposes (e.g., it will receive
836 .\" notification of tracee events and appears in
838 .\" output as the tracee's parent), but a
840 .\" by the tracee will still return the PID of the original parent.
843 but will not necessarily have stopped
844 by the completion of this call; use
846 to wait for the tracee to stop.
847 See the "Attaching and detaching" subsection for additional information.
853 Permission to perform a
855 is governed by a ptrace access mode
856 .B PTRACE_MODE_ATTACH_REALCREDS
859 .BR PTRACE_SEIZE " (since Linux 3.4)"
861 .\" Noted by Dmitry Levin:
863 .\" PTRACE_SEIZE was introduced by commit v3.1-rc1~308^2~28, but
864 .\" it had to be used along with a temporary flag PTRACE_SEIZE_DEVEL,
865 .\" which was removed later by commit v3.4-rc1~109^2~20.
867 .\" That is, [before] v3.4 we had a test mode of PTRACE_SEIZE API,
868 .\" which was not compatible with the current PTRACE_SEIZE API introduced
871 Attach to the process specified in
873 making it a tracee of the calling process.
877 does not stop the process.
878 Group-stops are reported as
882 returns the stop signal.
883 Automatically attached children stop with
891 signal delivered to them.
893 does not deliver an extra
902 The "seized" behavior just described is inherited by
903 children that are automatically attached using
904 .BR PTRACE_O_TRACEFORK ,
905 .BR PTRACE_O_TRACEVFORK ,
907 .BR PTRACE_O_TRACECLONE .
911 contains a bit mask of ptrace options to activate immediately.
913 Permission to perform a
915 is governed by a ptrace access mode
916 .B PTRACE_MODE_ATTACH_REALCREDS
920 .BR PTRACE_SECCOMP_GET_FILTER " (since Linux 4.4)"
921 .\" commit f8e529ed941ba2bbcbf310b575d968159ce7e895
922 This operation allows the tracer to dump the tracee's
926 is an integer specifying the index of the filter to be dumped.
927 The most recently installed filter has the index 0.
930 is greater than the number of installed filters,
931 the operation fails with the error
935 is either a pointer to a
936 .IR "struct sock_filter"
937 array that is large enough to store the BPF program,
938 or NULL if the program is not to be stored.
941 the return value is the number of instructions in the BPF program.
944 was NULL, then this return value can be used to correctly size the
945 .IR "struct sock_filter"
946 array passed in a subsequent call.
948 This operation fails with the error
950 if the caller does not have the
952 capability or if the caller is in strict or filter seccomp mode.
953 If the filter referred to by
955 is not a classic BPF filter, the operation fails with the error
958 This operation is available if the kernel was configured with both the
959 .B CONFIG_SECCOMP_FILTER
961 .B CONFIG_CHECKPOINT_RESTORE
965 Restart the stopped tracee as for
967 but first detach from it.
968 Under Linux, a tracee can be detached in this way regardless
969 of which method was used to initiate tracing.
974 .BR PTRACE_GET_THREAD_AREA " (since Linux 2.6.0)"
975 This operation performs a similar task to
976 .BR get_thread_area (2).
977 It reads the TLS entry in the GDT whose index is given in
979 placing a copy of the entry into the
980 .IR "struct user_desc"
984 .BR get_thread_area (2),
988 .IR "struct user_desc"
991 .BR PTRACE_SET_THREAD_AREA " (since Linux 2.6.0)"
992 This operation performs a similar task to
993 .BR set_thread_area (2).
994 It sets the TLS entry in the GDT whose index is given in
996 assigning it the data supplied in the
997 .IR "struct user_desc"
1001 .BR set_thread_area (2),
1005 .IR "struct user_desc"
1006 is ignored; in other words,
1007 this ptrace operation can't be used to allocate a free TLS entry.)
1009 .BR PTRACE_GET_SYSCALL_INFO " (since Linux 5.3)"
1010 .\" commit 201766a20e30f982ccfe36bebfad9602c3ff574a
1011 Retrieve information about the system call that caused the stop.
1012 The information is placed into the buffer pointed by the
1014 argument, which should be a pointer to a buffer of type
1015 .IR "struct ptrace_syscall_info" .
1018 argument contains the size of the buffer pointed to
1022 .IR "sizeof(struct ptrace_syscall_info)" ).
1023 The return value contains the number of bytes available
1024 to be written by the kernel.
1025 If the size of the data to be written by the kernel exceeds the size
1028 argument, the output data is truncated.
1031 .I ptrace_syscall_info
1032 structure contains the following fields:
1036 struct ptrace_syscall_info {
1037 __u8 op; /* Type of system call stop */
1038 __u32 arch; /* AUDIT_ARCH_* value; see seccomp(2) */
1039 __u64 instruction_pointer; /* CPU instruction pointer */
1040 __u64 stack_pointer; /* CPU stack pointer */
1042 struct { /* op == PTRACE_SYSCALL_INFO_ENTRY */
1043 __u64 nr; /* System call number */
1044 __u64 args[6]; /* System call arguments */
1046 struct { /* op == PTRACE_SYSCALL_INFO_EXIT */
1047 __s64 rval; /* System call return value */
1048 __u8 is_error; /* System call error flag;
1049 Boolean: does rval contain
1050 an error value (\-ERRCODE) or
1051 a nonerror return value? */
1053 struct { /* op == PTRACE_SYSCALL_INFO_SECCOMP */
1054 __u64 nr; /* System call number */
1055 __u64 args[6]; /* System call arguments */
1056 __u32 ret_data; /* SECCOMP_RET_DATA portion
1057 of SECCOMP_RET_TRACE
1068 .IR instruction_pointer ,
1071 fields are defined for all kinds of ptrace system call stops.
1072 The rest of the structure is a union; one should read only those fields
1073 that are meaningful for the kind of system call stop specified by the
1079 field has one of the following values (defined in
1080 .IR <linux/ptrace.h>)
1081 indicating what type of stop occurred and
1082 which part of the union is filled:
1085 .BR PTRACE_SYSCALL_INFO_ENTRY
1088 component of the union contains information relating to a
1089 system call entry stop.
1091 .BR PTRACE_SYSCALL_INFO_EXIT
1094 component of the union contains information relating to a
1095 system call exit stop.
1097 .BR PTRACE_SYSCALL_INFO_SECCOMP
1100 component of the union contains information relating to a
1101 .B PTRACE_EVENT_SECCOMP
1104 .BR PTRACE_SYSCALL_INFO_NONE
1105 No component of the union contains relevant information.
1108 .SS Death under ptrace
1109 When a (possibly multithreaded) process receives a killing signal
1110 (one whose disposition is set to
1112 and whose default action is to kill the process),
1114 Tracees report their death to their tracer(s).
1115 Notification of this event is delivered via
1118 Note that the killing signal will first cause signal-delivery-stop
1119 (on one tracee only),
1120 and only after it is injected by the tracer
1121 (or after it was dispatched to a thread which isn't traced),
1122 will death from the signal happen on
1124 tracees within a multithreaded process.
1125 (The term "signal-delivery-stop" is explained below.)
1128 does not generate signal-delivery-stop and
1129 therefore the tracer can't suppress it.
1131 kills even within system calls
1132 (syscall-exit-stop is not generated prior to death by
1134 The net effect is that
1136 always kills the process (all its threads),
1137 even if some threads of the process are ptraced.
1139 When the tracee calls
1141 it reports its death to its tracer.
1142 Other threads are not affected.
1144 When any thread executes
1146 every tracee in its thread group reports its death to its tracer.
1149 .B PTRACE_O_TRACEEXIT
1151 .B PTRACE_EVENT_EXIT
1152 will happen before actual death.
1153 This applies to exits via
1156 and signal deaths (except
1158 depending on the kernel version; see BUGS below),
1159 and when threads are torn down on
1161 in a multithreaded process.
1163 The tracer cannot assume that the ptrace-stopped tracee exists.
1164 There are many scenarios when the tracee may die while stopped (such as
1166 Therefore, the tracer must be prepared to handle an
1168 error on any ptrace operation.
1169 Unfortunately, the same error is returned if the tracee
1170 exists but is not ptrace-stopped
1171 (for commands which require a stopped tracee),
1172 or if it is not traced by the process which issued the ptrace call.
1173 The tracer needs to keep track of the stopped/running state of the tracee,
1176 as "tracee died unexpectedly" only if it knows that the tracee has
1177 been observed to enter ptrace-stop.
1178 Note that there is no guarantee that
1180 will reliably report the tracee's death status if a
1181 ptrace operation returned
1184 may return 0 instead.
1185 In other words, the tracee may be "not yet fully dead",
1186 but already refusing ptrace requests.
1188 The tracer can't assume that the tracee
1190 ends its life by reporting
1191 .I WIFEXITED(status)
1193 .IR WIFSIGNALED(status) ;
1194 there are cases where this does not occur.
1195 For example, if a thread other than thread group leader does an
1198 its PID will never be seen again,
1199 and any subsequent ptrace stops will be reported under
1200 the thread group leader's PID.
1202 A tracee can be in two states: running or stopped.
1203 For the purposes of ptrace, a tracee which is blocked in a system call
1208 is nevertheless considered to be running, even if the tracee is blocked
1210 The state of the tracee after
1212 is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
1213 won't work on it, and it will deliver
1216 but it also may be considered "stopped" because
1217 it is not executing instructions (is not scheduled), and if it was
1218 in group-stop before
1220 it will not respond to signals until
1224 There are many kinds of states when the tracee is stopped, and in ptrace
1225 discussions they are often conflated.
1226 Therefore, it is important to use precise terms.
1228 In this manual page, any stopped state in which the tracee is ready
1229 to accept ptrace commands from the tracer is called
1232 be further subdivided into
1233 .IR signal-delivery-stop ,
1236 .IR "PTRACE_EVENT stops" ,
1238 These stopped states are described in detail below.
1240 When the running tracee enters ptrace-stop, it notifies its tracer using
1242 (or one of the other "wait" system calls).
1243 Most of this manual page assumes that the tracer waits with:
1245 pid = waitpid(pid_or_minus_1, &status, __WALL);
1247 Ptrace-stopped tracees are reported as returns with
1250 .I WIFSTOPPED(status)
1253 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
1254 .\" I am not 100% sure there aren't ugly corner cases.) Are the
1255 .\" rules different if user wants to use waitid? Will waitid require
1261 flag does not include the
1265 flags, but implies their functionality.
1271 is not recommended: the "continued" state is per-process and
1272 consuming it can confuse the real parent of the tracee.
1278 to return 0 ("no wait results available yet")
1279 even if the tracer knows there should be a notification.
1285 ptrace(PTRACE_CONT, pid, 0L, 0L);
1286 if (errno == ESRCH) {
1287 /* tracee is dead */
1288 r = waitpid(tracee, &status, __WALL | WNOHANG);
1289 /* r can still be 0 here! */
1294 .\" waitid usage? WNOWAIT?
1295 .\" describe how wait notifications queue (or not queue)
1297 The following kinds of ptrace-stops exist: signal-delivery-stops,
1300 stops, syscall-stops.
1301 They all are reported by
1304 .I WIFSTOPPED(status)
1306 They may be differentiated by examining the value
1308 and if there is ambiguity in that value, by querying
1309 .BR PTRACE_GETSIGINFO .
1312 macro can't be used to perform this examination,
1313 because it returns the value
1314 .IR "(status>>8)\ &\ 0xff" .)
1315 .SS Signal-delivery-stop
1316 When a (possibly multithreaded) process receives any signal except
1318 the kernel selects an arbitrary thread which handles the signal.
1319 (If the signal is generated with
1321 the target thread can be explicitly selected by the caller.)
1322 If the selected thread is traced, it enters signal-delivery-stop.
1323 At this point, the signal is not yet delivered to the process,
1324 and can be suppressed by the tracer.
1325 If the tracer doesn't suppress the signal,
1326 it passes the signal to the tracee in the next ptrace restart request.
1327 This second step of signal delivery is called
1328 .I "signal injection"
1329 in this manual page.
1330 Note that if the signal is blocked,
1331 signal-delivery-stop doesn't happen until the signal is unblocked,
1332 with the usual exception that
1336 Signal-delivery-stop is observed by the tracer as
1339 .I WIFSTOPPED(status)
1340 true, with the signal returned by
1341 .IR WSTOPSIG(status) .
1344 this may be a different kind of ptrace-stop;
1345 see the "Syscall-stops" and "execve" sections below for details.
1348 returns a stopping signal, this may be a group-stop; see below.
1349 .SS Signal injection and suppression
1350 After signal-delivery-stop is observed by the tracer,
1351 the tracer should restart the tracee with the call
1353 ptrace(PTRACE_restart, pid, 0, sig)
1357 is one of the restarting ptrace requests.
1360 is 0, then a signal is not delivered.
1361 Otherwise, the signal
1364 This operation is called
1365 .I "signal injection"
1366 in this manual page, to distinguish it from signal-delivery-stop.
1370 value may be different from the
1372 value: the tracer can cause a different signal to be injected.
1374 Note that a suppressed signal still causes system calls to return
1376 In this case, system calls will be restarted: the tracer will
1377 observe the tracee to reexecute the interrupted system call (or
1378 .BR restart_syscall (2)
1379 system call for a few system calls which use a different mechanism
1380 for restarting) if the tracer uses
1381 .BR PTRACE_SYSCALL .
1382 Even system calls (such as
1384 which are not restartable after signal are restarted after
1385 signal is suppressed;
1386 however, kernel bugs exist which cause some system calls to fail with
1388 even though no observable signal is injected to the tracee.
1390 Restarting ptrace commands issued in ptrace-stops other than
1391 signal-delivery-stop are not guaranteed to inject a signal, even if
1394 No error is reported; a nonzero
1396 may simply be ignored.
1397 Ptrace users should not try to "create a new signal" this way: use
1401 The fact that signal injection requests may be ignored
1402 when restarting the tracee after
1403 ptrace stops that are not signal-delivery-stops
1404 is a cause of confusion among ptrace users.
1405 One typical scenario is that the tracer observes group-stop,
1406 mistakes it for signal-delivery-stop, restarts the tracee with
1408 ptrace(PTRACE_restart, pid, 0, stopsig)
1410 with the intention of injecting
1414 gets ignored and the tracee continues to run.
1418 signal has a side effect of waking up (all threads of)
1419 a group-stopped process.
1420 This side effect happens before signal-delivery-stop.
1421 The tracer can't suppress this side effect (it can
1422 only suppress signal injection, which only causes the
1424 handler to not be executed in the tracee, if such a handler is installed).
1425 In fact, waking up from group-stop may be followed by
1426 signal-delivery-stop for signal(s)
1429 if they were pending when
1434 may be not the first signal observed by the tracee after it was sent.
1436 Stopping signals cause (all threads of) a process to enter group-stop.
1437 This side effect happens after signal injection, and therefore can be
1438 suppressed by the tracer.
1440 In Linux 2.4 and earlier, the
1442 signal can't be injected.
1443 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
1446 .\" /* The debugger continued. Ignore SIGSTOP. */
1447 .\" if (signr == SIGSTOP)
1450 .B PTRACE_GETSIGINFO
1451 can be used to retrieve a
1453 structure which corresponds to the delivered signal.
1454 .B PTRACE_SETSIGINFO
1455 may be used to modify it.
1457 .B PTRACE_SETSIGINFO
1458 has been used to alter
1464 parameter in the restarting command must match,
1465 otherwise the result is undefined.
1467 When a (possibly multithreaded) process receives a stopping signal,
1469 If some threads are traced, they enter a group-stop.
1470 Note that the stopping signal will first cause signal-delivery-stop
1471 (on one tracee only), and only after it is injected by the tracer
1472 (or after it was dispatched to a thread which isn't traced),
1473 will group-stop be initiated on
1475 tracees within the multithreaded process.
1476 As usual, every tracee reports its group-stop separately
1477 to the corresponding tracer.
1479 Group-stop is observed by the tracer as
1482 .I WIFSTOPPED(status)
1483 true, with the stopping signal available via
1484 .IR WSTOPSIG(status) .
1485 The same result is returned by some other classes of ptrace-stops,
1486 therefore the recommended practice is to perform the call
1488 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
1490 The call can be avoided if the signal is not
1496 only these four signals are stopping signals.
1497 If the tracer sees something else, it can't be a group-stop.
1498 Otherwise, the tracer needs to call
1499 .BR PTRACE_GETSIGINFO .
1501 .B PTRACE_GETSIGINFO
1504 then it is definitely a group-stop.
1505 (Other failure codes are possible, such as
1507 ("no such process") if a
1511 If tracee was attached using
1513 group-stop is indicated by
1514 .BR PTRACE_EVENT_STOP :
1515 .IR "status>>16 == PTRACE_EVENT_STOP" .
1516 This allows detection of group-stops
1517 without requiring an extra
1518 .B PTRACE_GETSIGINFO
1522 after the tracer sees the tracee ptrace-stop and until it
1523 restarts or kills it, the tracee will not run,
1524 and will not send notifications (except
1526 death) to the tracer, even if the tracer enters into another
1530 The kernel behavior described in the previous paragraph
1531 causes a problem with transparent handling of stopping signals.
1532 If the tracer restarts the tracee after group-stop,
1534 is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
1535 If the tracer doesn't restart the tracee before entering into the next
1539 signals will not be reported to the tracer;
1540 this would cause the
1542 signals to have no effect on the tracee.
1544 Since Linux 3.4, there is a method to overcome this problem: instead of
1548 command can be used to restart a tracee in a way where it does not execute,
1549 but waits for a new event which it can report via
1552 it is restarted by a
1554 .SS PTRACE_EVENT stops
1557 options, the tracee will enter ptrace-stops called
1562 stops are observed by the tracer as
1565 .IR WIFSTOPPED(status) ,
1571 .BR PTRACE_EVENT_STOP ,
1572 returns the stopping signal if tracee is in a group-stop).
1573 An additional bit is set in the higher byte of the status word:
1578 ((PTRACE_EVENT_foo<<8) | SIGTRAP).
1580 The following events exist:
1582 .B PTRACE_EVENT_VFORK
1583 Stop before return from
1590 When the tracee is continued after this stop, it will wait for child to
1591 exit/exec before continuing its execution
1592 (in other words, the usual behavior on
1595 .B PTRACE_EVENT_FORK
1596 Stop before return from
1600 with the exit signal set to
1603 .B PTRACE_EVENT_CLONE
1604 Stop before return from
1607 .B PTRACE_EVENT_VFORK_DONE
1608 Stop before return from
1615 but after the child unblocked this tracee by exiting or execing.
1617 For all four stops described above,
1618 the stop occurs in the parent (i.e., the tracee),
1619 not in the newly created thread.
1620 .BR PTRACE_GETEVENTMSG
1621 can be used to retrieve the new thread's ID.
1623 .B PTRACE_EVENT_EXEC
1624 Stop before return from
1627 .BR PTRACE_GETEVENTMSG
1628 returns the former thread ID.
1630 .B PTRACE_EVENT_EXIT
1631 Stop before exit (including death from
1632 .BR exit_group (2)),
1633 signal death, or exit caused by
1635 in a multithreaded process.
1636 .B PTRACE_GETEVENTMSG
1637 returns the exit status.
1638 Registers can be examined
1639 (unlike when "real" exit happens).
1640 The tracee is still alive; it needs to be
1643 .BR PTRACE_DETACH ed
1646 .B PTRACE_EVENT_STOP
1649 command, or group-stop, or initial ptrace-stop when a new child is attached
1650 (only if attached using
1653 .B PTRACE_EVENT_SECCOMP
1656 rule on tracee syscall entry when
1657 .BR PTRACE_O_TRACESECCOMP
1658 has been set by the tracer.
1659 The seccomp event message data (from the
1660 .BR SECCOMP_RET_DATA
1661 portion of the seccomp filter rule) can be retrieved with
1662 .BR PTRACE_GETEVENTMSG .
1663 The semantics of this stop are described in
1664 detail in a separate section below.
1666 .B PTRACE_GETSIGINFO
1676 .IR "(event<<8)\ |\ SIGTRAP" .
1678 If the tracee was restarted by
1683 syscall-enter-stop just prior to entering any system call (which
1684 will not be executed if the restart was using
1686 regardless of any change made to registers at this point or how the
1687 tracee is restarted after this stop).
1688 No matter which method caused the syscall-entry-stop,
1689 if the tracer restarts the tracee with
1690 .BR PTRACE_SYSCALL ,
1691 the tracee enters syscall-exit-stop when the system call is finished,
1692 or if it is interrupted by a signal.
1693 (That is, signal-delivery-stop never happens between syscall-enter-stop
1694 and syscall-exit-stop; it happens
1696 syscall-exit-stop.).
1697 If the tracee is continued using any other method (including
1698 .BR PTRACE_SYSEMU ),
1699 no syscall-exit-stop occurs.
1700 Note that all mentions
1703 .BR PTRACE_SYSEMU_SINGLESTEP.
1705 However, even if the tracee was continued using
1706 .BR PTRACE_SYSCALL ,
1707 it is not guaranteed that the next stop will be a syscall-exit-stop.
1708 Other possibilities are that the tracee may stop in a
1710 stop (including seccomp stops), exit (if it entered
1713 .BR exit_group (2)),
1716 or die silently (if it is a thread group leader, the
1718 happened in another thread,
1719 and that thread is not traced by the same tracer;
1720 this situation is discussed later).
1722 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1725 .I WIFSTOPPED(status)
1731 .B PTRACE_O_TRACESYSGOOD
1732 option was set by the tracer, then
1735 .IR "(SIGTRAP\ |\ 0x80)" .
1737 Syscall-stops can be distinguished from signal-delivery-stop with
1740 .BR PTRACE_GETSIGINFO
1741 for the following cases:
1745 was delivered as a result of a user-space action,
1746 for example, a system call
1751 expiration of a POSIX timer,
1752 change of state on a POSIX message queue,
1753 or completion of an asynchronous I/O request.
1755 .IR si_code " == SI_KERNEL (0x80)"
1757 was sent by the kernel.
1759 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1760 This is a syscall-stop.
1762 However, syscall-stops happen very often (twice per system call),
1764 .B PTRACE_GETSIGINFO
1765 for every syscall-stop may be somewhat expensive.
1767 Some architectures allow the cases to be distinguished
1768 by examining registers.
1769 For example, on x86,
1773 in syscall-enter-stop.
1776 (like any other signal) always happens
1781 almost never contains
1785 looks like "syscall-stop which is not syscall-enter-stop";
1786 in other words, it looks like a
1787 "stray syscall-exit-stop" and can be detected this way.
1788 But such detection is fragile and is best avoided.
1791 .B PTRACE_O_TRACESYSGOOD
1792 option is the recommended method to distinguish syscall-stops
1793 from other kinds of ptrace-stops,
1794 since it is reliable and does not incur a performance penalty.
1796 Syscall-enter-stop and syscall-exit-stop are
1797 indistinguishable from each other by the tracer.
1798 The tracer needs to keep track of the sequence of
1799 ptrace-stops in order to not misinterpret syscall-enter-stop as
1800 syscall-exit-stop or vice versa.
1801 In general, a syscall-enter-stop is
1802 always followed by syscall-exit-stop,
1804 stop, or the tracee's death;
1805 no other kinds of ptrace-stop can occur in between.
1806 However, note that seccomp stops (see below) can cause syscall-exit-stops,
1807 without preceding syscall-entry-stops.
1808 If seccomp is in use, care needs
1809 to be taken not to misinterpret such stops as syscall-entry-stops.
1811 If after syscall-enter-stop,
1812 the tracer uses a restarting command other than
1813 .BR PTRACE_SYSCALL ,
1814 syscall-exit-stop is not generated.
1816 .B PTRACE_GETSIGINFO
1817 on syscall-stops returns
1826 .IR (SIGTRAP|0x80) .
1828 .SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to 4.7)
1830 .BR PTRACE_EVENT_SECCOMP
1831 stops and their interaction with other kinds
1832 of ptrace stops has changed between kernel versions.
1833 This documents the behavior
1834 from their introduction until Linux 4.7 (inclusive).
1835 The behavior in later kernel versions is documented in the next section.
1838 .BR PTRACE_EVENT_SECCOMP
1839 stop occurs whenever a
1840 .BR SECCOMP_RET_TRACE
1842 This is independent of which methods was used to restart the system call.
1843 Notably, seccomp still runs even if the tracee was restarted using
1845 and this system call is unconditionally skipped.
1847 Restarts from this stop will behave as if the stop had occurred right
1848 before the system call in question.
1853 will normally cause a subsequent syscall-entry-stop.
1854 However, if after the
1855 .BR PTRACE_EVENT_SECCOMP
1856 the system call number is negative,
1857 both the syscall-entry-stop and the system call itself will be skipped.
1858 This means that if the system call number is negative after a
1859 .BR PTRACE_EVENT_SECCOMP
1860 and the tracee is restarted using
1861 .BR PTRACE_SYSCALL ,
1862 the next observed stop will be a syscall-exit-stop,
1863 rather than the syscall-entry-stop that might have been expected.
1865 .SS PTRACE_EVENT_SECCOMP stops (since Linux 4.8)
1866 Starting with Linux 4.8,
1867 .\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea
1869 .BR PTRACE_EVENT_SECCOMP
1870 stop was reordered to occur between syscall-entry-stop and
1872 Note that seccomp no longer runs (and no
1873 .B PTRACE_EVENT_SECCOMP
1874 will be reported) if the system call is skipped due to
1878 .B PTRACE_EVENT_SECCOMP
1879 stop functions comparably
1880 to a syscall-entry-stop (i.e., continuations using
1882 will cause syscall-exit-stops,
1883 the system call number may be changed and any other modified registers
1884 are visible to the to-be-executed system call as well).
1885 Note that there may be,
1886 but need not have been a preceding syscall-entry-stop.
1889 .BR PTRACE_EVENT_SECCOMP
1890 stop, seccomp will be rerun, with a
1891 .BR SECCOMP_RET_TRACE
1892 rule now functioning the same as a
1893 .BR SECCOMP_RET_ALLOW .
1894 Specifically, this means that if registers are not modified during the
1895 .BR PTRACE_EVENT_SECCOMP
1896 stop, the system call will then be allowed.
1898 .SS PTRACE_SINGLESTEP stops
1899 [Details of these kinds of stops are yet to be documented.]
1902 .\" document stops occurring with PTRACE_SINGLESTEP
1904 .SS Informational and restarting ptrace commands
1905 Most ptrace commands (all except
1908 .BR PTRACE_TRACEME ,
1909 .BR PTRACE_INTERRUPT ,
1912 require the tracee to be in a ptrace-stop, otherwise they fail with
1915 When the tracee is in ptrace-stop,
1916 the tracer can read and write data to
1917 the tracee using informational commands.
1918 These commands leave the tracee in ptrace-stopped state:
1922 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1923 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1924 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1925 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1926 ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
1927 ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
1928 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1929 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1930 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
1931 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1935 Note that some errors are not reported.
1936 For example, setting signal information
1938 may have no effect in some ptrace-stops, yet the call may succeed
1939 (return 0 and not set
1942 .B PTRACE_GETEVENTMSG
1943 may succeed and return some random value if current ptrace-stop
1944 is not documented as returning a meaningful event message.
1948 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1951 The tracee's current flags are replaced.
1952 Flags are inherited by new tracees created and "auto-attached" via active
1953 .BR PTRACE_O_TRACEFORK ,
1954 .BR PTRACE_O_TRACEVFORK ,
1956 .BR PTRACE_O_TRACECLONE
1959 Another group of commands makes the ptrace-stopped tracee run.
1962 ptrace(cmd, pid, 0, sig);
1970 .BR PTRACE_SYSCALL ,
1971 .BR PTRACE_SINGLESTEP ,
1974 .BR PTRACE_SYSEMU_SINGLESTEP .
1975 If the tracee is in signal-delivery-stop,
1977 is the signal to be injected (if it is nonzero).
1981 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
1982 recommended practice is to always pass 0 in
1984 .SS Attaching and detaching
1985 A thread can be attached to the tracer using the call
1987 ptrace(PTRACE_ATTACH, pid, 0, 0);
1991 ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
1997 If the tracer wants this
1999 to have no effect, it needs to suppress it.
2000 Note that if other signals are concurrently sent to
2001 this thread during attach,
2002 the tracer may see the tracee enter signal-delivery-stop
2003 with other signal(s) first!
2004 The usual practice is to reinject these signals until
2006 is seen, then suppress
2009 The design bug here is that a ptrace attach and a concurrently delivered
2011 may race and the concurrent
2015 .\" FIXME Describe how to attach to a thread which is already group-stopped.
2017 Since attaching sends
2019 and the tracer usually suppresses it, this may cause a stray
2021 return from the currently executing system call in the tracee,
2022 as described in the "Signal injection and suppression" section.
2026 can be used instead of
2029 does not stop the attached process.
2031 it after attach (or at any other time) without sending it any signals,
2038 ptrace(PTRACE_TRACEME, 0, 0, 0);
2040 turns the calling thread into a tracee.
2041 The thread continues to run (doesn't enter ptrace-stop).
2042 A common practice is to follow the
2048 and allow the parent (which is our tracer now) to observe our
2049 signal-delivery-stop.
2052 .BR PTRACE_O_TRACEFORK ,
2053 .BR PTRACE_O_TRACEVFORK ,
2055 .BR PTRACE_O_TRACECLONE
2056 options are in effect, then children created by, respectively,
2066 with the exit signal set to
2070 are automatically attached to the same tracer which traced their parent.
2072 is delivered to the children, causing them to enter
2073 signal-delivery-stop after they exit the system call which created them.
2075 Detaching of the tracee is performed by:
2077 ptrace(PTRACE_DETACH, pid, 0, sig);
2080 is a restarting operation;
2081 therefore it requires the tracee to be in ptrace-stop.
2082 If the tracee is in signal-delivery-stop, a signal can be injected.
2085 parameter may be silently ignored.
2087 If the tracee is running when the tracer wants to detach it,
2088 the usual solution is to send
2092 to make sure it goes to the correct thread),
2093 wait for the tracee to stop in signal-delivery-stop for
2095 and then detach it (suppressing
2098 A design bug is that this can race with concurrent
2100 Another complication is that the tracee may enter other ptrace-stops
2101 and needs to be restarted and waited for again, until
2104 Yet another complication is to be sure that
2105 the tracee is not already ptrace-stopped,
2106 because no signal delivery happens while it is\(emnot even
2108 .\" FIXME Describe how to detach from a group-stopped tracee so that it
2109 .\" doesn't run, but continues to wait for SIGCONT.
2111 If the tracer dies, all tracees are automatically detached and restarted,
2112 unless they were in group-stop.
2113 Handling of restart from group-stop is currently buggy,
2114 but the "as planned" behavior is to leave tracee stopped and waiting for
2116 If the tracee is restarted from signal-delivery-stop,
2117 the pending signal is injected.
2118 .SS execve(2) under ptrace
2119 .\" clone(2) CLONE_THREAD says:
2120 .\" If any of the threads in a thread group performs an execve(2),
2121 .\" then all threads other than the thread group leader are terminated,
2122 .\" and the new program is executed in the thread group leader.
2124 When one thread in a multithreaded process calls
2126 the kernel destroys all other threads in the process,
2127 .\" In kernel 3.1 sources, see fs/exec.c::de_thread()
2128 and resets the thread ID of the execing thread to the
2129 thread group ID (process ID).
2130 (Or, to put things another way, when a multithreaded process does an
2132 at completion of the call, it appears as though the
2134 occurred in the thread group leader, regardless of which thread did the
2136 This resetting of the thread ID looks very confusing to tracers:
2138 All other threads stop in
2139 .B PTRACE_EVENT_EXIT
2141 .BR PTRACE_O_TRACEEXIT
2142 option was turned on.
2143 Then all other threads except the thread group leader report
2144 death as if they exited via
2148 The execing tracee changes its thread ID while it is in the
2150 (Remember, under ptrace, the "pid" returned from
2152 or fed into ptrace calls, is the tracee's thread ID.)
2153 That is, the tracee's thread ID is reset to be the same as its process ID,
2154 which is the same as the thread group leader's thread ID.
2157 .B PTRACE_EVENT_EXEC
2158 stop happens, if the
2159 .BR PTRACE_O_TRACEEXEC
2160 option was turned on.
2162 If the thread group leader has reported its
2163 .B PTRACE_EVENT_EXIT
2165 it appears to the tracer that
2166 the dead thread leader "reappears from nowhere".
2167 (Note: the thread group leader does not report death via
2168 .I WIFEXITED(status)
2169 until there is at least one other live thread.
2170 This eliminates the possibility that the tracer will see
2171 it dying and then reappearing.)
2172 If the thread group leader was still alive,
2173 for the tracer this may look as if thread group leader
2174 returns from a different system call than it entered,
2175 or even "returned from a system call even though
2176 it was not in any system call".
2177 If the thread group leader was not traced
2178 (or was traced by a different tracer), then during
2180 it will appear as if it has become a tracee of
2181 the tracer of the execing tracee.
2183 All of the above effects are the artifacts of
2184 the thread ID change in the tracee.
2187 .B PTRACE_O_TRACEEXEC
2188 option is the recommended tool for dealing with this situation.
2190 .BR PTRACE_EVENT_EXEC
2195 In this stop, the tracer can use
2196 .B PTRACE_GETEVENTMSG
2197 to retrieve the tracee's former thread ID.
2198 (This feature was introduced in Linux 3.0.)
2200 .B PTRACE_O_TRACEEXEC
2201 option disables legacy
2206 When the tracer receives
2207 .B PTRACE_EVENT_EXEC
2209 it is guaranteed that except this tracee and the thread group leader,
2210 no other threads from the process are alive.
2213 .B PTRACE_EVENT_EXEC
2215 the tracer should clean up all its internal
2216 data structures describing the threads of this process,
2217 and retain only one data structure\(emone which
2218 describes the single still running tracee, with
2220 thread ID == thread group ID == process ID.
2222 Example: two threads call
2227 *** we get syscall-enter-stop in thread 1: **
2228 PID1 execve("/bin/foo", "foo" <unfinished ...>
2229 *** we issue PTRACE_SYSCALL for thread 1 **
2230 *** we get syscall-enter-stop in thread 2: **
2231 PID2 execve("/bin/bar", "bar" <unfinished ...>
2232 *** we issue PTRACE_SYSCALL for thread 2 **
2233 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
2234 *** we get syscall-exit-stop for PID0: **
2235 PID0 <... execve resumed> ) = 0
2239 .B PTRACE_O_TRACEEXEC
2242 in effect for the execing tracee,
2243 and if the tracee was
2244 .BR PTRACE_ATTACH ed
2247 the kernel delivers an extra
2252 This is an ordinary signal (similar to one which can be
2255 not a special kind of ptrace-stop.
2257 .B PTRACE_GETSIGINFO
2258 for this signal returns
2262 This signal may be blocked by signal mask,
2263 and thus may be delivered (much) later.
2265 Usually, the tracer (for example,
2267 would not want to show this extra post-execve
2269 signal to the user, and would suppress its delivery to the tracee (if
2273 it is a killing signal).
2274 However, determining
2277 to suppress is not easy.
2279 .B PTRACE_O_TRACEEXEC
2282 and thus suppressing this extra
2284 is the recommended approach.
2286 The ptrace API (ab)uses the standard UNIX parent/child signaling over
2288 This used to cause the real parent of the process to stop receiving
2291 notifications when the child process is traced by some other process.
2293 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
2294 exist; see BUGS below.
2296 As of Linux 2.6.38, the following is believed to work correctly:
2298 exit/death by signal is reported first to the tracer, then,
2299 when the tracer consumes the
2301 result, to the real parent (to the real parent only when the
2302 whole multithreaded process exits).
2303 If the tracer and the real parent are the same process,
2304 the report is sent only once.
2308 requests return the requested data (but see NOTES),
2310 .B PTRACE_SECCOMP_GET_FILTER
2311 request returns the number of instructions in the BPF program, and
2312 other requests return zero.
2314 On error, all requests return \-1, and
2316 is set appropriately.
2317 Since the value returned by a successful
2319 request may be \-1, the caller must clear
2321 before the call, and then check it afterward
2322 to determine whether or not an error occurred.
2326 (i386 only) There was an error with allocating or freeing a debug register.
2329 There was an attempt to read from or write to an invalid area in
2330 the tracer's or the tracee's memory,
2331 probably because the area wasn't mapped or accessible.
2332 Unfortunately, under Linux, different variations of this fault
2337 more or less arbitrarily.
2340 An attempt was made to set an invalid option.
2344 is invalid, or an attempt was made to read from or
2345 write to an invalid area in the tracer's or the tracee's memory,
2346 or there was a word-alignment violation,
2347 or an invalid signal was specified during a restart request.
2350 The specified process cannot be traced.
2351 This could be because the
2352 tracer has insufficient privileges (the required capability is
2353 .BR CAP_SYS_PTRACE );
2354 unprivileged processes cannot trace processes that they
2355 cannot send signals to or those running
2356 set-user-ID/set-group-ID programs, for obvious reasons.
2357 Alternatively, the process may already be being traced,
2358 or (on kernels before 2.6.26) be
2363 The specified process does not exist, or is not currently being traced
2364 by the caller, or is not stopped
2365 (for requests that require a stopped tracee).
2369 Although arguments to
2371 are interpreted according to the prototype given,
2372 glibc currently declares
2374 as a variadic function with only the
2377 It is recommended to always supply four arguments,
2378 even if the requested operation does not use them,
2379 setting unused/ignored arguments to
2384 In Linux kernels before 2.6.26,
2385 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
2387 the process with PID 1, may not be traced.
2389 A tracees parent continues to be the tracer even if that tracer calls
2392 The layout of the contents of memory and the USER area are
2393 quite operating-system- and architecture-specific.
2394 The offset supplied, and the data returned,
2395 might not entirely match with the definition of
2397 .\" See http://lkml.org/lkml/2008/5/8/375
2399 The size of a "word" is determined by the operating-system variant
2400 (e.g., for 32-bit Linux it is 32 bits).
2402 This page documents the way the
2404 call works currently in Linux.
2405 Its behavior differs significantly on other flavors of UNIX.
2408 is highly specific to the operating system and architecture.
2410 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2412 .SS Ptrace access mode checking
2413 Various parts of the kernel-user-space API (not just
2415 operations), require so-called "ptrace access mode" checks,
2416 whose outcome determines whether an operation is permitted
2417 (or, in a few cases, causes a "read" operation to return sanitized data).
2418 These checks are performed in cases where one process can
2419 inspect sensitive information about,
2420 or in some cases modify the state of, another process.
2421 The checks are based on factors such as the credentials and capabilities
2422 of the two processes,
2423 whether or not the "target" process is dumpable,
2424 and the results of checks performed by any enabled Linux Security Module
2425 (LSM)\(emfor example, SELinux, Yama, or Smack\(emand by the commoncap LSM
2426 (which is always invoked).
2428 Prior to Linux 2.6.27, all access checks were of a single type.
2430 .\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd
2431 two access mode levels are distinguished:
2433 .BR PTRACE_MODE_READ
2434 For "read" operations or other operations that are less dangerous,
2436 .BR get_robust_list (2);
2439 .IR /proc/[pid]/auxv ,
2440 .IR /proc/[pid]/environ ,
2442 .IR /proc/[pid]/stat ;
2446 .IR /proc/[pid]/ns/*
2449 .BR PTRACE_MODE_ATTACH
2450 For "write" operations, or other operations that are more dangerous,
2451 such as: ptrace attaching
2452 .RB ( PTRACE_ATTACH )
2455 .BR process_vm_writev (2).
2456 .RB ( PTRACE_MODE_ATTACH
2457 was effectively the default before Linux 2.6.27.)
2459 .\" Regarding the above description of the distinction between
2460 .\" PTRACE_MODE_READ and PTRACE_MODE_ATTACH, Stephen Smalley notes:
2462 .\" That was the intent when the distinction was introduced, but it doesn't
2463 .\" appear to have been properly maintained, e.g. there is now a common
2464 .\" helper lock_trace() that is used for
2465 .\" /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and
2466 .\" PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show(). Likely
2467 .\" should review and make them consistent. There was also some debate
2468 .\" about proper handling of /proc/pid/fd. Arguably that one might belong
2469 .\" back in the _ATTACH camp.
2473 .\" commit caaee6234d05a58c5b4d05e7bf766131b810a657
2474 the above access mode checks are combined (ORed) with
2475 one of the following modifiers:
2477 .B PTRACE_MODE_FSCREDS
2478 Use the caller's filesystem UID and GID (see
2479 .BR credentials (7))
2480 or effective capabilities for LSM checks.
2482 .B PTRACE_MODE_REALCREDS
2483 Use the caller's real UID and GID or permitted capabilities for LSM checks.
2484 This was effectively the default before Linux 4.5.
2486 Because combining one of the credential modifiers with one of
2487 the aforementioned access modes is typical,
2488 some macros are defined in the kernel sources for the combinations:
2490 .B PTRACE_MODE_READ_FSCREDS
2492 .BR "PTRACE_MODE_READ | PTRACE_MODE_FSCREDS" .
2494 .B PTRACE_MODE_READ_REALCREDS
2496 .BR "PTRACE_MODE_READ | PTRACE_MODE_REALCREDS" .
2498 .B PTRACE_MODE_ATTACH_FSCREDS
2500 .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS" .
2502 .B PTRACE_MODE_ATTACH_REALCREDS
2504 .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" .
2506 One further modifier can be ORed with the access mode:
2508 .BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)"
2509 .\" commit 69f594a38967f4540ce7a29b3fd214e68a8330bd
2510 .\" Just for /proc/pid/stat
2511 Don't audit this access mode check.
2512 This modifier is employed for ptrace access mode checks
2513 (such as checks when reading
2514 .IR /proc/[pid]/stat )
2515 that merely cause the output to be filtered or sanitized,
2516 rather than causing an error to be returned to the caller.
2517 In these cases, accessing the file is not a security violation and
2518 there is no reason to generate a security audit record.
2519 This modifier suppresses the generation of
2520 such an audit record for the particular access check.
2522 Note that all of the
2524 constants described in this subsection are kernel-internal,
2525 and not visible to user space.
2526 The constant names are mentioned here in order to label the various kinds of
2527 ptrace access mode checks that are performed for various system calls
2528 and accesses to various pseudofiles (e.g., under
2530 These names are used in other manual pages to provide a simple
2531 shorthand for labeling the different kernel checks.
2533 The algorithm employed for ptrace access mode checking determines whether
2534 the calling process is allowed to perform the corresponding action
2535 on the target process.
2536 (In the case of opening
2538 files, the "calling process" is the one opening the file,
2539 and the process with the corresponding PID is the "target process".)
2540 The algorithm is as follows:
2542 If the calling thread and the target thread are in the same
2543 thread group, access is always allowed.
2545 If the access mode specifies
2546 .BR PTRACE_MODE_FSCREDS ,
2547 then, for the check in the next step,
2548 employ the caller's filesystem UID and GID.
2550 .BR credentials (7),
2551 the filesystem UID and GID almost always have the same values
2552 as the corresponding effective IDs.)
2554 Otherwise, the access mode specifies
2555 .BR PTRACE_MODE_REALCREDS ,
2556 so use the caller's real UID and GID for the checks in the next step.
2557 (Most APIs that check the caller's UID and GID use the effective IDs.
2558 For historical reasons, the
2559 .BR PTRACE_MODE_REALCREDS
2560 check uses the real IDs instead.)
2564 of the following is true:
2567 The real, effective, and saved-set user IDs of the target
2568 match the caller's user ID,
2570 the real, effective, and saved-set group IDs of the target
2571 match the caller's group ID.
2575 capability in the user namespace of the target.
2578 Deny access if the target process "dumpable" attribute has a value other than 1
2579 .RB ( SUID_DUMP_USER ;
2580 see the discussion of
2584 and the caller does not have the
2586 capability in the user namespace of the target process.
2589 .IR security_ptrace_access_check ()
2590 interface is invoked to see if ptrace access is permitted.
2591 The results depend on the LSM(s).
2592 The implementation of this interface in the commoncap LSM performs
2593 the following steps:
2594 .\" (in cap_ptrace_access_check()):
2597 If the access mode includes
2598 .BR PTRACE_MODE_FSCREDS ,
2599 then use the caller's
2602 in the following check;
2603 otherwise (the access mode specifies
2604 .BR PTRACE_MODE_REALCREDS ,
2605 so) use the caller's
2611 of the following is true:
2614 The caller and the target process are in the same user namespace,
2615 and the caller's capabilities are a superset of the target process's
2621 capability in the target process's user namespace.
2624 Note that the commoncap LSM does not distinguish between
2627 .BR PTRACE_MODE_ATTACH .
2630 If access has not been denied by any of the preceding steps,
2631 then access is allowed.
2633 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2635 .SS /proc/sys/kernel/yama/ptrace_scope
2636 On systems with the Yama Linux Security Module (LSM) installed
2637 (i.e., the kernel was configured with
2638 .BR CONFIG_SECURITY_YAMA ),
2640 .I /proc/sys/kernel/yama/ptrace_scope
2641 file (available since Linux 3.4)
2642 .\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
2643 can be used to restrict the ability to trace a process with
2645 (and thus also the ability to use tools such as
2649 The goal of such restrictions is to prevent attack escalation whereby
2650 a compromised process can ptrace-attach to other sensitive processes
2651 (e.g., a GPG agent or an SSH session) owned by the user in order
2652 to gain additional credentials that may exist in memory
2653 and thus expand the scope of the attack.
2655 More precisely, the Yama LSM limits two types of operations:
2657 Any operation that performs a ptrace access mode
2658 .BR PTRACE_MODE_ATTACH
2659 check\(emfor example,
2662 (See the "Ptrace access mode checking" discussion above.)
2666 .BR PTRACE_TRACEME .
2668 A process that has the
2670 capability can update the
2671 .IR /proc/sys/kernel/yama/ptrace_scope
2672 file with one of the following values:
2674 0 ("classic ptrace permissions")
2675 No additional restrictions on operations that perform
2676 .BR PTRACE_MODE_ATTACH
2677 checks (beyond those imposed by the commoncap and other LSMs).
2683 1 ("restricted ptrace") [default value]
2684 When performing an operation that requires a
2685 .BR PTRACE_MODE_ATTACH
2686 check, the calling process must either have the
2688 capability in the user namespace of the target process or
2689 it must have a predefined relationship with the target process.
2691 the predefined relationship is that the target process
2692 must be a descendant of the caller.
2694 A target process can employ the
2697 operation to declare an additional PID that is allowed to perform
2698 .BR PTRACE_MODE_ATTACH
2699 operations on the target.
2700 See the kernel source file
2701 .IR Documentation/admin\-guide/LSM/Yama.rst
2702 .\" commit 90bb766440f2147486a2acc3e793d7b8348b0c22
2704 .IR Documentation/security/Yama.txt
2706 for further details.
2712 2 ("admin-only attach")
2713 Only processes with the
2715 capability in the user namespace of the target process may perform
2716 .BR PTRACE_MODE_ATTACH
2717 operations or trace children that employ
2718 .BR PTRACE_TRACEME .
2721 No process may perform
2722 .BR PTRACE_MODE_ATTACH
2723 operations or trace children that employ
2724 .BR PTRACE_TRACEME .
2726 Once this value has been written to the file, it cannot be changed.
2728 With respect to values 1 and 2,
2729 note that creating a new user namespace effectively removes the
2730 protection offered by Yama.
2731 This is because a process in the parent user namespace whose effective
2732 UID matches the UID of the creator of a child namespace
2733 has all capabilities (including
2734 .BR CAP_SYS_PTRACE )
2735 when performing operations within the child user namespace
2736 (and further-removed descendants of that namespace).
2737 Consequently, when a process tries to use user namespaces to sandbox itself,
2738 it inadvertently weakens the protections offered by the Yama LSM.
2740 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2742 .SS C library/kernel differences
2743 At the system call level, the
2744 .BR PTRACE_PEEKTEXT ,
2745 .BR PTRACE_PEEKDATA ,
2748 requests have a different API: they store the result
2749 at the address specified by the
2751 parameter, and the return value is the error flag.
2752 The glibc wrapper function provides the API given in DESCRIPTION above,
2753 with the result being returned via the function return value.
2755 On hosts with 2.6 kernel headers,
2756 .B PTRACE_SETOPTIONS
2757 is declared with a different value than the one for 2.4.
2758 This leads to applications compiled with 2.6 kernel
2759 headers failing when run on 2.4 kernels.
2760 This can be worked around by redefining
2761 .B PTRACE_SETOPTIONS
2763 .BR PTRACE_OLDSETOPTIONS ,
2766 Group-stop notifications are sent to the tracer, but not to real parent.
2767 Last confirmed on 2.6.38.6.
2769 If a thread group leader is traced and exits by calling
2771 .\" Note from Denys Vlasenko:
2772 .\" Here "exits" means any kind of death - _exit, exit_group,
2773 .\" signal death. Signal death and exit_group cases are trivial,
2774 .\" though: since signal death and exit_group kill all other threads
2775 .\" too, "until all other threads exit" thing happens rather soon
2776 .\" in these cases. Therefore, only _exit presents observably
2777 .\" puzzling behavior to ptrace users: thread leader _exit's,
2778 .\" but WIFEXITED isn't reported! We are trying to explain here
2781 .B PTRACE_EVENT_EXIT
2782 stop will happen for it (if requested), but the subsequent
2784 notification will not be delivered until all other threads exit.
2785 As explained above, if one of other threads calls
2787 the death of the thread group leader will
2790 If the execed thread is not traced by this tracer,
2791 the tracer will never know that
2794 One possible workaround is to
2796 the thread group leader instead of restarting it in this case.
2797 Last confirmed on 2.6.38.6.
2798 .\" FIXME . need to test/verify this scenario
2802 signal may still cause a
2803 .B PTRACE_EVENT_EXIT
2804 stop before actual signal death.
2805 This may be changed in the future;
2807 is meant to always immediately kill tasks even under ptrace.
2808 Last confirmed on Linux 3.13.
2810 Some system calls return with
2812 if a signal was sent to a tracee, but delivery was suppressed by the tracer.
2813 (This is very typical operation: it is usually
2814 done by debuggers on every attach, in order to not introduce
2817 As of Linux 3.2.9, the following system calls are affected
2818 (this list is likely incomplete):
2825 The usual symptom of this bug is that when you attach to
2826 a quiescent process with the command
2830 strace \-p <process-ID>
2834 then, instead of the usual
2835 and expected one-line output such as
2839 restart_syscall(<... resuming interrupted call ...>_
2847 select(6, [5], NULL, [5], NULL_
2851 ('_' denotes the cursor position), you observe more than one line.
2856 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
2861 What is not visible here is that the process was blocked in
2868 to return to user space with the error
2870 In this particular case, the program reacted to
2872 by checking the current time, and then executing
2875 (Programs which do not expect such "stray"
2877 errors may behave in an unintended way upon an
2881 Contrary to the normal rules, the glibc wrapper for
2901 .BR capabilities (7),