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>
11 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
12 .\" This is free documentation; you can redistribute it and/or
13 .\" modify it under the terms of the GNU General Public License as
14 .\" published by the Free Software Foundation; either version 2 of
15 .\" the License, or (at your option) any later version.
17 .\" The GNU General Public License's references to "object code"
18 .\" and "executables" are to be interpreted as the output of any
19 .\" document formatting or typesetting system, including
20 .\" intermediate and printed output.
22 .\" This manual is distributed in the hope that it will be useful,
23 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
24 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 .\" GNU General Public License for more details.
27 .\" You should have received a copy of the GNU General Public
28 .\" License along with this manual; if not, see
29 .\" <http://www.gnu.org/licenses/>.
32 .\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith <faith@cs.unc.edu>
33 .\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond <esr@thyrsus.com>
34 .\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer <aeb@cwi.nl>
35 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
36 .\" Added notes on capability requirements
38 .\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com>
39 .\" Added PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO,
40 .\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP
41 .\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.)
42 .\" 2011-09, major update by Denys Vlasenko <vda.linux@googlemail.com>
44 .TH PTRACE 2 2014-08-19 "Linux" "Linux Programmer's Manual"
46 ptrace \- process trace
49 .B #include <sys/ptrace.h>
51 .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
52 .BI " void *" addr ", void *" data );
57 system call provides a means by which one process (the "tracer")
58 may observe and control the execution of another process (the "tracee"),
59 and examine and change the tracee's memory and registers.
60 It is primarily used to implement breakpoint debugging and system
63 A tracee first needs to be attached to the tracer.
64 Attachment and subsequent commands are per thread:
65 in a multithreaded process,
66 every thread can be individually attached to a
67 (potentially different) tracer,
68 or left not attached and thus not debugged.
69 Therefore, "tracee" always means "(one) thread",
70 never "a (possibly multithreaded) process".
71 Ptrace commands are always sent to
72 a specific tracee using a call of the form
74 ptrace(PTRACE_foo, pid, ...)
78 is the thread ID of the corresponding Linux thread.
80 (Note that in this page, a "multithreaded process"
81 means a thread group consisting of threads created using the
86 A process can initiate a trace by calling
88 and having the resulting child do a
90 followed (typically) by an
92 Alternatively, one process may commence tracing another process using
97 While being traced, the tracee will stop each time a signal is delivered,
98 even if the signal is being ignored.
101 which has its usual effect.)
102 The tracer will be notified at its next call to
104 (or one of the related "wait" system calls); that call will return a
106 value containing information that indicates
107 the cause of the stop in the tracee.
108 While the tracee is stopped,
109 the tracer can use various ptrace requests to inspect and modify the tracee.
110 The tracer then causes the tracee to continue,
111 optionally ignoring the delivered signal
112 (or even delivering a different signal instead).
115 .B PTRACE_O_TRACEEXEC
116 option is not in effect, all successful calls to
118 by the traced process will cause it to be sent a
121 giving the parent a chance to gain control before the new program
124 When the tracer is finished tracing, it can cause the tracee to continue
125 executing in a normal, untraced mode via
130 determines the action to be performed:
133 Indicate that this process is to be traced by its parent.
134 A process probably shouldn't make this request if its parent
135 isn't expecting to trace it.
144 request is used only by the tracee;
145 the remaining requests are used only by the tracer.
146 In the following requests,
148 specifies the thread ID of the tracee to be acted on.
149 For requests other than
152 .BR PTRACE_INTERRUPT ,
155 the tracee must be stopped.
157 .BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA
158 Read a word at the address
160 in the tracee's memory, returning the word as the result of the
163 Linux does not have separate text and data address spaces,
164 so these two requests are currently equivalent.
166 is ignored; but see NOTES.)
169 .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
170 .\" and that is the name that seems common on other systems.
171 Read a word at offset
173 in the tracee's USER area,
174 which holds the registers and other information about the process
177 The word is returned as the result of the
180 Typically, the offset must be word-aligned, though this might vary by
184 is ignored; but see NOTES.)
186 .BR PTRACE_POKETEXT ", " PTRACE_POKEDATA
191 in the tracee's memory.
195 .BR PTRACE_PEEKDATA ,
196 these two requests are currently equivalent.
199 .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
200 .\" and that is the name that seems common on other systems.
205 in the tracee's USER area.
207 .BR PTRACE_PEEKUSER ,
208 the offset must typically be word-aligned.
209 In order to maintain the integrity of the kernel,
210 some modifications to the USER area are disallowed.
211 .\" FIXME In the preceding sentence, which modifications are disallowed,
212 .\" and when they are disallowed, how does user space discover that fact?
214 .BR PTRACE_GETREGS ", " PTRACE_GETFPREGS
215 Copy the tracee's general-purpose or floating-point registers,
216 respectively, to the address
221 for information on the format of this data.
224 Note that SPARC systems have the meaning of
230 is ignored and the registers are copied to the address
235 are not present on all architectures.
237 .BR PTRACE_GETREGSET " (since Linux 2.6.34)"
238 Read the tracee's registers.
240 specifies, in an architecture-dependent way, the type of registers to be read.
242 (with numerical value 1)
243 usually results in reading of general-purpose registers.
244 If the CPU has, for example,
245 floating-point and/or vector registers, they can be retrieved by setting
253 which describes the destination buffer's location and length.
254 On return, the kernel modifies
256 to indicate the actual number of bytes returned.
258 .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
259 Modify the tracee's general-purpose or floating-point registers,
260 respectively, from the address
264 .BR PTRACE_POKEUSER ,
265 some general-purpose register modifications may be disallowed.
266 .\" FIXME . In the preceding sentence, which modifications are disallowed,
267 .\" and when they are disallowed, how does user space discover that fact?
270 Note that SPARC systems have the meaning of
276 is ignored and the registers are copied from the address
281 are not present on all architectures.
283 .BR PTRACE_SETREGSET " (since Linux 2.6.34)"
284 Modify the tracee's registers.
290 .BR PTRACE_GETREGSET .
292 .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
293 Retrieve information about the signal that caused the stop.
298 from the tracee to the address
304 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
305 Set signal information:
308 structure from the address
310 in the tracer to the tracee.
311 This will affect only signals that would normally be delivered to
312 the tracee and were caught by the tracer.
313 It may be difficult to tell
314 these normal signals from synthetic signals generated by
320 .BR PTRACE_PEEKSIGINFO " (since Linux 3.10)"
321 .\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4
324 structures without removing signals from a queue.
327 .I ptrace_peeksiginfo_args
328 structure that specifies the ordinal position from which
329 copying of signals should start,
330 and the number of signals to copy.
332 structures are copied into the buffer pointed to by
334 The return value contains the number of copied signals (zero indicates
335 that there is no signal corresponding to the specified ordinal position).
341 field includes information
344 etc.) that are not otherwise exposed to user space.
348 struct ptrace_peeksiginfo_args {
349 u64 off; /* Ordinal position in queue at which
350 to start copying signals */
351 u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */
352 s32 nr; /* Number of signals to copy */
356 Currently, there is only one flag,
357 .BR PTRACE_PEEKSIGINFO_SHARED ,
358 for dumping signals from the process-wide signal queue.
359 If this flag is not set,
360 signals are read from the per-thread queue of the specified thread.
364 .BR PTRACE_GETSIGMASK " (since Linux 3.11)"
365 .\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
366 Place a copy of the mask of blocked signals (see
368 in the buffer pointed to by
370 which should be a pointer to a buffer of type
374 argument contains the size of the buffer pointed to by
377 .IR sizeof(sigset_t) ).
379 .BR PTRACE_SETSIGMASK " (since Linux 3.11)"
380 Change the mask of blocked signals (see
382 to the value specified in the buffer pointed to by
384 which should be a pointer to a buffer of type
388 argument contains the size of the buffer pointed to by
391 .IR sizeof(sigset_t) ).
393 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
394 Set ptrace options from
399 is interpreted as a bit mask of options,
400 which are specified by the following flags:
403 .BR PTRACE_O_EXITKILL " (since Linux 3.8)"
404 .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123
405 If a tracer sets this flag, a
407 signal will be sent to every tracee if the tracer exits.
408 This option is useful for ptrace jailers that
409 want to ensure that tracees can never escape the tracer's control.
411 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
412 Stop the tracee at the next
414 and automatically start tracing the newly cloned process,
415 which will start with a
424 by the tracer will return a
429 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
432 The PID of the new process can be retrieved with
433 .BR PTRACE_GETEVENTMSG .
435 This option may not catch
443 .B PTRACE_EVENT_VFORK
444 will be delivered instead
446 .B PTRACE_O_TRACEVFORK
447 is set; otherwise if the tracee calls
449 with the exit signal set to
453 .B PTRACE_O_TRACEFORK
456 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
457 Stop the tracee at the next
461 by the tracer will return a
466 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
469 If the execing thread is not a thread group leader,
470 the thread ID is reset to thread group leader's ID before this stop.
471 Since Linux 3.0, the former thread ID can be retrieved with
472 .BR PTRACE_GETEVENTMSG .
474 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
475 Stop the tracee at exit.
478 by the tracer will return a
483 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
486 The tracee's exit status can be retrieved with
487 .BR PTRACE_GETEVENTMSG .
489 The tracee is stopped early during process exit,
490 when registers are still available,
491 allowing the tracer to see where the exit occurred,
492 whereas the normal exit notification is done after the process
494 Even though context is available,
495 the tracer cannot prevent the exit from happening at this point.
497 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
498 Stop the tracee at the next
500 and automatically start tracing the newly forked process,
501 which will start with a
510 by the tracer will return a
515 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
518 The PID of the new process can be retrieved with
519 .BR PTRACE_GETEVENTMSG .
521 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
522 When delivering system call traps, set bit 7 in the signal number
524 .IR "SIGTRAP|0x80" ).
525 This makes it easy for the tracer to distinguish
526 normal traps from those caused by a system call.
527 .RB ( PTRACE_O_TRACESYSGOOD
528 may not work on all architectures.)
530 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
531 Stop the tracee at the next
533 and automatically start tracing the newly vforked process,
534 which will start with a
543 by the tracer will return a
548 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
551 The PID of the new process can be retrieved with
552 .BR PTRACE_GETEVENTMSG .
554 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
555 Stop the tracee at the completion of the next
559 by the tracer will return a
564 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
567 The PID of the new process can (since Linux 2.6.18) be retrieved with
568 .BR PTRACE_GETEVENTMSG .
571 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
572 Retrieve a message (as an
573 .IR "unsigned long" )
574 about the ptrace event
575 that just happened, placing it at the address
579 .BR PTRACE_EVENT_EXIT ,
580 this is the tracee's exit status.
582 .BR PTRACE_EVENT_FORK ,
583 .BR PTRACE_EVENT_VFORK ,
584 .BR PTRACE_EVENT_VFORK_DONE ,
586 .BR PTRACE_EVENT_CLONE ,
587 this is the PID of the new process.
592 Restart the stopped tracee process.
596 it is interpreted as the number of a signal to be delivered to the tracee;
597 otherwise, no signal is delivered.
598 Thus, for example, the tracer can control
599 whether a signal sent to the tracee is delivered or not.
603 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
604 Restart the stopped tracee as for
606 but arrange for the tracee to be stopped at
607 the next entry to or exit from a system call,
608 or after execution of a single instruction, respectively.
609 (The tracee will also, as usual, be stopped upon receipt of a signal.)
610 From the tracer's perspective, the tracee will appear to have been
611 stopped by receipt of a
615 for example, the idea is to inspect
616 the arguments to the system call at the first stop,
619 and inspect the return value of the system call at the second stop.
622 argument is treated as for
627 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
630 continue and stop on entry to the next system call,
631 which will not be executed.
633 .BR PTRACE_SYSEMU_SINGLESTEP ,
634 do the same but also singlestep if not a system call.
635 This call is used by programs like
636 User Mode Linux that want to emulate all the tracee's system calls.
639 argument is treated as for
644 These requests are currently
646 supported only on x86.
648 .BR PTRACE_LISTEN " (since Linux 3.4)"
649 Restart the stopped tracee, but prevent it from executing.
650 The resulting state of the tracee is similar to a process which
651 has been stopped by a
653 (or other stopping signal).
654 See the "group-stop" subsection for additional information.
656 works only on tracees attached by
668 .I This operation is deprecated; do not use it!
677 is that it requires the tracee to be in signal-delivery-stop,
678 otherwise it may not work
679 (i.e., may complete successfully but won't kill the tracee).
680 By contrast, sending a
682 directly has no such limitation.
683 .\" [Note from Denys Vlasenko:
684 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
685 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
687 .BR PTRACE_INTERRUPT " (since Linux 3.4)"
689 If the tracee is running or sleeping in kernel space and
692 the system call is interrupted and syscall-exit-stop is reported.
693 (The interrupted system call is restarted when the tracee is restarted.)
694 If the tracee was already stopped by a signal and
697 the tracee stops with
701 returns the stop signal.
702 If any other ptrace-stop is generated at the same time (for example,
703 if a signal is sent to the tracee), this ptrace-stop happens.
704 If none of the above applies (for example, if the tracee is running in user
705 space), it stops with
712 only works on tracees attached by
716 Attach to the process specified in
718 making it a tracee of the calling process.
719 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
720 .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
721 .\" Basically, it's not true for any Linux in practical use.
722 .\" ; the behavior of the tracee is as if it had done a
723 .\" .BR PTRACE_TRACEME .
724 .\" The calling process actually becomes the parent of the tracee
725 .\" process for most purposes (e.g., it will receive
726 .\" notification of tracee events and appears in
728 .\" output as the tracee's parent), but a
730 .\" by the tracee will still return the PID of the original parent.
733 but will not necessarily have stopped
734 by the completion of this call; use
736 to wait for the tracee to stop.
737 See the "Attaching and detaching" subsection for additional information.
743 .BR PTRACE_SEIZE " (since Linux 3.4)"
744 Attach to the process specified in
746 making it a tracee of the calling process.
750 does not stop the process.
761 contains a bit mask of ptrace options to activate immediately.
764 Restart the stopped tracee as for
766 but first detach from it.
767 Under Linux, a tracee can be detached in this way regardless
768 of which method was used to initiate tracing.
771 .SS Death under ptrace
772 When a (possibly multithreaded) process receives a killing signal
773 (one whose disposition is set to
775 and whose default action is to kill the process),
777 Tracees report their death to their tracer(s).
778 Notification of this event is delivered via
781 Note that the killing signal will first cause signal-delivery-stop
782 (on one tracee only),
783 and only after it is injected by the tracer
784 (or after it was dispatched to a thread which isn't traced),
785 will death from the signal happen on
787 tracees within a multithreaded process.
788 (The term "signal-delivery-stop" is explained below.)
791 does not generate signal-delivery-stop and
792 therefore the tracer can't suppress it.
794 kills even within system calls
795 (syscall-exit-stop is not generated prior to death by
797 The net effect is that
799 always kills the process (all its threads),
800 even if some threads of the process are ptraced.
802 When the tracee calls
804 it reports its death to its tracer.
805 Other threads are not affected.
807 When any thread executes
809 every tracee in its thread group reports its death to its tracer.
812 .B PTRACE_O_TRACEEXIT
815 will happen before actual death.
816 This applies to exits via
819 and signal deaths (except
821 and when threads are torn down on
823 in a multithreaded process.
825 The tracer cannot assume that the ptrace-stopped tracee exists.
826 There are many scenarios when the tracee may die while stopped (such as
828 Therefore, the tracer must be prepared to handle an
830 error on any ptrace operation.
831 Unfortunately, the same error is returned if the tracee
832 exists but is not ptrace-stopped
833 (for commands which require a stopped tracee),
834 or if it is not traced by the process which issued the ptrace call.
835 The tracer needs to keep track of the stopped/running state of the tracee,
838 as "tracee died unexpectedly" only if it knows that the tracee has
839 been observed to enter ptrace-stop.
840 Note that there is no guarantee that
842 will reliably report the tracee's death status if a
843 ptrace operation returned
846 may return 0 instead.
847 In other words, the tracee may be "not yet fully dead",
848 but already refusing ptrace requests.
850 The tracer can't assume that the tracee
852 ends its life by reporting
855 .IR WIFSIGNALED(status) ;
856 there are cases where this does not occur.
857 For example, if a thread other than thread group leader does an
860 its PID will never be seen again,
861 and any subsequent ptrace stops will be reported under
862 the thread group leader's PID.
864 A tracee can be in two states: running or stopped.
865 For the purposes of ptrace, a tracee which is blocked in a system call
870 is nevertheless considered to be running, even if the tracee is blocked
872 The state of the tracee after
874 is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
875 won't work on it, and it will deliver
878 but it also may be considered "stopped" because
879 it is not executing instructions (is not scheduled), and if it was
882 it will not respond to signals until
886 There are many kinds of states when the tracee is stopped, and in ptrace
887 discussions they are often conflated.
888 Therefore, it is important to use precise terms.
890 In this manual page, any stopped state in which the tracee is ready
891 to accept ptrace commands from the tracer is called
894 be further subdivided into
895 .IR signal-delivery-stop ,
899 These stopped states are described in detail below.
901 When the running tracee enters ptrace-stop, it notifies its tracer using
903 (or one of the other "wait" system calls).
904 Most of this manual page assumes that the tracer waits with:
906 pid = waitpid(pid_or_minus_1, &status, __WALL);
908 Ptrace-stopped tracees are reported as returns with
911 .I WIFSTOPPED(status)
914 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
915 .\" I am not 100% sure there aren't ugly corner cases.) Are the
916 .\" rules different if user wants to use waitid? Will waitid require
922 flag does not include the
926 flags, but implies their functionality.
932 is not recommended: the "continued" state is per-process and
933 consuming it can confuse the real parent of the tracee.
939 to return 0 ("no wait results available yet")
940 even if the tracer knows there should be a notification.
945 ptrace(PTRACE_CONT, pid, 0L, 0L);
946 if (errno == ESRCH) {
948 r = waitpid(tracee, &status, __WALL | WNOHANG);
949 /* r can still be 0 here! */
953 .\" waitid usage? WNOWAIT?
954 .\" describe how wait notifications queue (or not queue)
956 The following kinds of ptrace-stops exist: signal-delivery-stops,
959 stops, syscall-stops.
960 They all are reported by
963 .I WIFSTOPPED(status)
965 They may be differentiated by examining the value
967 and if there is ambiguity in that value, by querying
968 .BR PTRACE_GETSIGINFO .
971 macro can't be used to perform this examination,
972 because it returns the value
973 .IR "(status>>8)\ &\ 0xff" .)
974 .SS Signal-delivery-stop
975 When a (possibly multithreaded) process receives any signal except
977 the kernel selects an arbitrary thread which handles the signal.
978 (If the signal is generated with
980 the target thread can be explicitly selected by the caller.)
981 If the selected thread is traced, it enters signal-delivery-stop.
982 At this point, the signal is not yet delivered to the process,
983 and can be suppressed by the tracer.
984 If the tracer doesn't suppress the signal,
985 it passes the signal to the tracee in the next ptrace restart request.
986 This second step of signal delivery is called
987 .I "signal injection"
989 Note that if the signal is blocked,
990 signal-delivery-stop doesn't happen until the signal is unblocked,
991 with the usual exception that
995 Signal-delivery-stop is observed by the tracer as
998 .I WIFSTOPPED(status)
999 true, with the signal returned by
1000 .IR WSTOPSIG(status) .
1003 this may be a different kind of ptrace-stop;
1004 see the "Syscall-stops" and "execve" sections below for details.
1007 returns a stopping signal, this may be a group-stop; see below.
1008 .SS Signal injection and suppression
1009 After signal-delivery-stop is observed by the tracer,
1010 the tracer should restart the tracee with the call
1012 ptrace(PTRACE_restart, pid, 0, sig)
1016 is one of the restarting ptrace requests.
1019 is 0, then a signal is not delivered.
1020 Otherwise, the signal
1023 This operation is called
1024 .I "signal injection"
1025 in this manual page, to distinguish it from signal-delivery-stop.
1029 value may be different from the
1031 value: the tracer can cause a different signal to be injected.
1033 Note that a suppressed signal still causes system calls to return
1035 In this case, system calls will be restarted: the tracer will
1036 observe the tracee to reexecute the interrupted system call (or
1037 .BR restart_syscall (2)
1038 system call for a few system calls which use a different mechanism
1039 for restarting) if the tracer uses
1040 .BR PTRACE_SYSCALL .
1041 Even system calls (such as
1043 which are not restartable after signal are restarted after
1044 signal is suppressed;
1045 however, kernel bugs exist which cause some system calls to fail with
1047 even though no observable signal is injected to the tracee.
1049 Restarting ptrace commands issued in ptrace-stops other than
1050 signal-delivery-stop are not guaranteed to inject a signal, even if
1053 No error is reported; a nonzero
1055 may simply be ignored.
1056 Ptrace users should not try to "create a new signal" this way: use
1060 The fact that signal injection requests may be ignored
1061 when restarting the tracee after
1062 ptrace stops that are not signal-delivery-stops
1063 is a cause of confusion among ptrace users.
1064 One typical scenario is that the tracer observes group-stop,
1065 mistakes it for signal-delivery-stop, restarts the tracee with
1067 ptrace(PTRACE_restart, pid, 0, stopsig)
1069 with the intention of injecting
1073 gets ignored and the tracee continues to run.
1077 signal has a side effect of waking up (all threads of)
1078 a group-stopped process.
1079 This side effect happens before signal-delivery-stop.
1080 The tracer can't suppress this side effect (it can
1081 only suppress signal injection, which only causes the
1083 handler to not be executed in the tracee, if such a handler is installed).
1084 In fact, waking up from group-stop may be followed by
1085 signal-delivery-stop for signal(s)
1088 if they were pending when
1093 may be not the first signal observed by the tracee after it was sent.
1095 Stopping signals cause (all threads of) a process to enter group-stop.
1096 This side effect happens after signal injection, and therefore can be
1097 suppressed by the tracer.
1099 In Linux 2.4 and earlier, the
1101 signal can't be injected.
1102 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
1105 .\" /* The debugger continued. Ignore SIGSTOP. */
1106 .\" if (signr == SIGSTOP)
1109 .B PTRACE_GETSIGINFO
1110 can be used to retrieve a
1112 structure which corresponds to the delivered signal.
1113 .B PTRACE_SETSIGINFO
1114 may be used to modify it.
1116 .B PTRACE_SETSIGINFO
1117 has been used to alter
1123 parameter in the restarting command must match,
1124 otherwise the result is undefined.
1126 When a (possibly multithreaded) process receives a stopping signal,
1128 If some threads are traced, they enter a group-stop.
1129 Note that the stopping signal will first cause signal-delivery-stop
1130 (on one tracee only), and only after it is injected by the tracer
1131 (or after it was dispatched to a thread which isn't traced),
1132 will group-stop be initiated on
1134 tracees within the multithreaded process.
1135 As usual, every tracee reports its group-stop separately
1136 to the corresponding tracer.
1138 Group-stop is observed by the tracer as
1141 .I WIFSTOPPED(status)
1142 true, with the stopping signal available via
1143 .IR WSTOPSIG(status) .
1144 The same result is returned by some other classes of ptrace-stops,
1145 therefore the recommended practice is to perform the call
1147 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
1149 The call can be avoided if the signal is not
1155 only these four signals are stopping signals.
1156 If the tracer sees something else, it can't be a group-stop.
1157 Otherwise, the tracer needs to call
1158 .BR PTRACE_GETSIGINFO .
1160 .B PTRACE_GETSIGINFO
1163 then it is definitely a group-stop.
1164 (Other failure codes are possible, such as
1166 ("no such process") if a
1170 If tracee was attached using
1172 group-stop is indicated by
1173 .BR PTRACE_EVENT_STOP :
1174 .IR "status>>16 == PTRACE_EVENT_STOP" .
1175 This allows detection of group-stops
1176 without requiring an extra
1177 .B PTRACE_GETSIGINFO
1181 after the tracer sees the tracee ptrace-stop and until it
1182 restarts or kills it, the tracee will not run,
1183 and will not send notifications (except
1185 death) to the tracer, even if the tracer enters into another
1189 The kernel behavior described in the previous paragraph
1190 causes a problem with transparent handling of stopping signals.
1191 If the tracer restarts the tracee after group-stop,
1193 is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
1194 If the tracer doesn't restart the tracee before entering into the next
1198 signals will not be reported to the tracer;
1199 this would cause the
1201 signals to have no effect on the tracee.
1203 Since Linux 3.4, there is a method to overcome this problem: instead of
1207 command can be used to restart a tracee in a way where it does not execute,
1208 but waits for a new event which it can report via
1211 it is restarted by a
1213 .SS PTRACE_EVENT stops
1216 options, the tracee will enter ptrace-stops called
1221 stops are observed by the tracer as
1224 .IR WIFSTOPPED(status) ,
1229 An additional bit is set in the higher byte of the status word:
1234 (SIGTRAP | PTRACE_EVENT_foo << 8).
1236 The following events exist:
1238 .B PTRACE_EVENT_VFORK
1239 Stop before return from
1246 When the tracee is continued after this stop, it will wait for child to
1247 exit/exec before continuing its execution
1248 (in other words, the usual behavior on
1251 .B PTRACE_EVENT_FORK
1252 Stop before return from
1256 with the exit signal set to
1259 .B PTRACE_EVENT_CLONE
1260 Stop before return from
1263 .B PTRACE_EVENT_VFORK_DONE
1264 Stop before return from
1271 but after the child unblocked this tracee by exiting or execing.
1273 For all four stops described above,
1274 the stop occurs in the parent (i.e., the tracee),
1275 not in the newly created thread.
1276 .BR PTRACE_GETEVENTMSG
1277 can be used to retrieve the new thread's ID.
1279 .B PTRACE_EVENT_EXEC
1280 Stop before return from
1283 .BR PTRACE_GETEVENTMSG
1284 returns the former thread ID.
1286 .B PTRACE_EVENT_EXIT
1287 Stop before exit (including death from
1288 .BR exit_group (2)),
1289 signal death, or exit caused by
1291 in a multithreaded process.
1292 .B PTRACE_GETEVENTMSG
1293 returns the exit status.
1294 Registers can be examined
1295 (unlike when "real" exit happens).
1296 The tracee is still alive; it needs to be
1299 .BR PTRACE_DETACH ed
1302 .B PTRACE_EVENT_STOP
1305 command, or group-stop, or initial ptrace-stop when a new child is attached
1306 (only if attached using
1309 .B PTRACE_EVENT_STOP
1314 .B PTRACE_GETSIGINFO
1324 .IR "(event<<8)\ |\ SIGTRAP" .
1326 If the tracee was restarted by
1327 .BR PTRACE_SYSCALL ,
1329 syscall-enter-stop just prior to entering any system call.
1330 If the tracer restarts the tracee with
1331 .BR PTRACE_SYSCALL ,
1332 the tracee enters syscall-exit-stop when the system call is finished,
1333 or if it is interrupted by a signal.
1334 (That is, signal-delivery-stop never happens between syscall-enter-stop
1335 and syscall-exit-stop; it happens
1339 Other possibilities are that the tracee may stop in a
1341 stop, exit (if it entered
1344 .BR exit_group (2)),
1347 or die silently (if it is a thread group leader, the
1349 happened in another thread,
1350 and that thread is not traced by the same tracer;
1351 this situation is discussed later).
1353 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1356 .I WIFSTOPPED(status)
1362 .B PTRACE_O_TRACESYSGOOD
1363 option was set by the tracer, then
1366 .IR "(SIGTRAP\ |\ 0x80)" .
1368 Syscall-stops can be distinguished from signal-delivery-stop with
1371 .BR PTRACE_GETSIGINFO
1372 for the following cases:
1376 was delivered as a result of a user-space action,
1377 for example, a system call
1382 expiration of a POSIX timer,
1383 change of state on a POSIX message queue,
1384 or completion of an asynchronous I/O request.
1386 .IR si_code " == SI_KERNEL (0x80)"
1388 was sent by the kernel.
1390 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1391 This is a syscall-stop.
1393 However, syscall-stops happen very often (twice per system call),
1395 .B PTRACE_GETSIGINFO
1396 for every syscall-stop may be somewhat expensive.
1398 Some architectures allow the cases to be distinguished
1399 by examining registers.
1400 For example, on x86,
1404 in syscall-enter-stop.
1407 (like any other signal) always happens
1412 almost never contains
1416 looks like "syscall-stop which is not syscall-enter-stop";
1417 in other words, it looks like a
1418 "stray syscall-exit-stop" and can be detected this way.
1419 But such detection is fragile and is best avoided.
1422 .B PTRACE_O_TRACESYSGOOD
1423 option is the recommended method to distinguish syscall-stops
1424 from other kinds of ptrace-stops,
1425 since it is reliable and does not incur a performance penalty.
1427 Syscall-enter-stop and syscall-exit-stop are
1428 indistinguishable from each other by the tracer.
1429 The tracer needs to keep track of the sequence of
1430 ptrace-stops in order to not misinterpret syscall-enter-stop as
1431 syscall-exit-stop or vice versa.
1432 The rule is that syscall-enter-stop is
1433 always followed by syscall-exit-stop,
1435 stop or the tracee's death;
1436 no other kinds of ptrace-stop can occur in between.
1438 If after syscall-enter-stop,
1439 the tracer uses a restarting command other than
1440 .BR PTRACE_SYSCALL ,
1441 syscall-exit-stop is not generated.
1443 .B PTRACE_GETSIGINFO
1444 on syscall-stops returns
1453 .IR (SIGTRAP|0x80) .
1454 .SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops
1455 [Details of these kinds of stops are yet to be documented.]
1458 .\" document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
1459 .\" PTRACE_SYSEMU_SINGLESTEP
1460 .SS Informational and restarting ptrace commands
1461 Most ptrace commands (all except
1464 .BR PTRACE_TRACEME ,
1465 .BR PTRACE_INTERRUPT ,
1468 require the tracee to be in a ptrace-stop, otherwise they fail with
1471 When the tracee is in ptrace-stop,
1472 the tracer can read and write data to
1473 the tracee using informational commands.
1474 These commands leave the tracee in ptrace-stopped state:
1477 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1478 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1479 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1480 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1481 ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
1482 ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
1483 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1484 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1485 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
1486 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1489 Note that some errors are not reported.
1490 For example, setting signal information
1492 may have no effect in some ptrace-stops, yet the call may succeed
1493 (return 0 and not set
1496 .B PTRACE_GETEVENTMSG
1497 may succeed and return some random value if current ptrace-stop
1498 is not documented as returning a meaningful event message.
1502 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1505 The tracee's current flags are replaced.
1506 Flags are inherited by new tracees created and "auto-attached" via active
1507 .BR PTRACE_O_TRACEFORK ,
1508 .BR PTRACE_O_TRACEVFORK ,
1510 .BR PTRACE_O_TRACECLONE
1513 Another group of commands makes the ptrace-stopped tracee run.
1516 ptrace(cmd, pid, 0, sig);
1524 .BR PTRACE_SYSCALL ,
1525 .BR PTRACE_SINGLESTEP ,
1528 .BR PTRACE_SYSEMU_SINGLESTEP .
1529 If the tracee is in signal-delivery-stop,
1531 is the signal to be injected (if it is nonzero).
1535 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
1536 recommended practice is to always pass 0 in
1538 .SS Attaching and detaching
1539 A thread can be attached to the tracer using the call
1541 ptrace(PTRACE_ATTACH, pid, 0, 0);
1545 ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
1551 If the tracer wants this
1553 to have no effect, it needs to suppress it.
1554 Note that if other signals are concurrently sent to
1555 this thread during attach,
1556 the tracer may see the tracee enter signal-delivery-stop
1557 with other signal(s) first!
1558 The usual practice is to reinject these signals until
1560 is seen, then suppress
1563 The design bug here is that a ptrace attach and a concurrently delivered
1565 may race and the concurrent
1569 .\" FIXME . Describe how to attach to a thread which is already group-stopped.
1571 Since attaching sends
1573 and the tracer usually suppresses it, this may cause a stray
1575 return from the currently executing system call in the tracee,
1576 as described in the "Signal injection and suppression" section.
1580 can be used instead of
1583 does not stop the attached process.
1585 it after attach (or at any other time) without sending it any signals,
1592 ptrace(PTRACE_TRACEME, 0, 0, 0);
1594 turns the calling thread into a tracee.
1595 The thread continues to run (doesn't enter ptrace-stop).
1596 A common practice is to follow the
1602 and allow the parent (which is our tracer now) to observe our
1603 signal-delivery-stop.
1606 .BR PTRACE_O_TRACEFORK ,
1607 .BR PTRACE_O_TRACEVFORK ,
1609 .BR PTRACE_O_TRACECLONE
1610 options are in effect, then children created by, respectively,
1620 with the exit signal set to
1624 are automatically attached to the same tracer which traced their parent.
1626 is delivered to the children, causing them to enter
1627 signal-delivery-stop after they exit the system call which created them.
1629 Detaching of the tracee is performed by:
1631 ptrace(PTRACE_DETACH, pid, 0, sig);
1634 is a restarting operation;
1635 therefore it requires the tracee to be in ptrace-stop.
1636 If the tracee is in signal-delivery-stop, a signal can be injected.
1639 parameter may be silently ignored.
1641 If the tracee is running when the tracer wants to detach it,
1642 the usual solution is to send
1646 to make sure it goes to the correct thread),
1647 wait for the tracee to stop in signal-delivery-stop for
1649 and then detach it (suppressing
1652 A design bug is that this can race with concurrent
1654 Another complication is that the tracee may enter other ptrace-stops
1655 and needs to be restarted and waited for again, until
1658 Yet another complication is to be sure that
1659 the tracee is not already ptrace-stopped,
1660 because no signal delivery happens while it is\(emnot even
1662 .\" FIXME . Describe how to detach from a group-stopped tracee so that it
1663 .\" doesn't run, but continues to wait for SIGCONT.
1665 If the tracer dies, all tracees are automatically detached and restarted,
1666 unless they were in group-stop.
1667 Handling of restart from group-stop is currently buggy,
1668 but the "as planned" behavior is to leave tracee stopped and waiting for
1670 If the tracee is restarted from signal-delivery-stop,
1671 the pending signal is injected.
1672 .SS execve(2) under ptrace
1673 .\" clone(2) CLONE_THREAD says:
1674 .\" If any of the threads in a thread group performs an execve(2),
1675 .\" then all threads other than the thread group leader are terminated,
1676 .\" and the new program is executed in the thread group leader.
1678 When one thread in a multithreaded process calls
1680 the kernel destroys all other threads in the process,
1681 .\" In kernel 3.1 sources, see fs/exec.c::de_thread()
1682 and resets the thread ID of the execing thread to the
1683 thread group ID (process ID).
1684 (Or, to put things another way, when a multithreaded process does an
1686 at completion of the call, it appears as though the
1688 occurred in the thread group leader, regardless of which thread did the
1690 This resetting of the thread ID looks very confusing to tracers:
1692 All other threads stop in
1693 .B PTRACE_EVENT_EXIT
1695 .BR PTRACE_O_TRACEEXIT
1696 option was turned on.
1697 Then all other threads except the thread group leader report
1698 death as if they exited via
1702 The execing tracee changes its thread ID while it is in the
1704 (Remember, under ptrace, the "pid" returned from
1706 or fed into ptrace calls, is the tracee's thread ID.)
1707 That is, the tracee's thread ID is reset to be the same as its process ID,
1708 which is the same as the thread group leader's thread ID.
1711 .B PTRACE_EVENT_EXEC
1712 stop happens, if the
1713 .BR PTRACE_O_TRACEEXEC
1714 option was turned on.
1716 If the thread group leader has reported its
1717 .B PTRACE_EVENT_EXIT
1719 it appears to the tracer that
1720 the dead thread leader "reappears from nowhere".
1721 (Note: the thread group leader does not report death via
1722 .I WIFEXITED(status)
1723 until there is at least one other live thread.
1724 This eliminates the possibility that the tracer will see
1725 it dying and then reappearing.)
1726 If the thread group leader was still alive,
1727 for the tracer this may look as if thread group leader
1728 returns from a different system call than it entered,
1729 or even "returned from a system call even though
1730 it was not in any system call".
1731 If the thread group leader was not traced
1732 (or was traced by a different tracer), then during
1734 it will appear as if it has become a tracee of
1735 the tracer of the execing tracee.
1737 All of the above effects are the artifacts of
1738 the thread ID change in the tracee.
1741 .B PTRACE_O_TRACEEXEC
1742 option is the recommended tool for dealing with this situation.
1744 .BR PTRACE_EVENT_EXEC
1749 In this stop, the tracer can use
1750 .B PTRACE_GETEVENTMSG
1751 to retrieve the tracee's former thread ID.
1752 (This feature was introduced in Linux 3.0).
1754 .B PTRACE_O_TRACEEXEC
1755 option disables legacy
1760 When the tracer receives
1761 .B PTRACE_EVENT_EXEC
1763 it is guaranteed that except this tracee and the thread group leader,
1764 no other threads from the process are alive.
1767 .B PTRACE_EVENT_EXEC
1769 the tracer should clean up all its internal
1770 data structures describing the threads of this process,
1771 and retain only one data structure\(emone which
1772 describes the single still running tracee, with
1774 thread ID == thread group ID == process ID.
1776 Example: two threads call
1781 *** we get syscall-enter-stop in thread 1: **
1782 PID1 execve("/bin/foo", "foo" <unfinished ...>
1783 *** we issue PTRACE_SYSCALL for thread 1 **
1784 *** we get syscall-enter-stop in thread 2: **
1785 PID2 execve("/bin/bar", "bar" <unfinished ...>
1786 *** we issue PTRACE_SYSCALL for thread 2 **
1787 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
1788 *** we get syscall-exit-stop for PID0: **
1789 PID0 <... execve resumed> ) = 0
1793 .B PTRACE_O_TRACEEXEC
1796 in effect for the execing tracee, the kernel delivers an extra
1801 This is an ordinary signal (similar to one which can be
1804 not a special kind of ptrace-stop.
1806 .B PTRACE_GETSIGINFO
1807 for this signal returns
1811 This signal may be blocked by signal mask,
1812 and thus may be delivered (much) later.
1814 Usually, the tracer (for example,
1816 would not want to show this extra post-execve
1818 signal to the user, and would suppress its delivery to the tracee (if
1822 it is a killing signal).
1823 However, determining
1826 to suppress is not easy.
1828 .B PTRACE_O_TRACEEXEC
1829 option and thus suppressing this extra
1831 is the recommended approach.
1833 The ptrace API (ab)uses the standard UNIX parent/child signaling over
1835 This used to cause the real parent of the process to stop receiving
1838 notifications when the child process is traced by some other process.
1840 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
1841 exist; see BUGS below.
1843 As of Linux 2.6.38, the following is believed to work correctly:
1845 exit/death by signal is reported first to the tracer, then,
1846 when the tracer consumes the
1848 result, to the real parent (to the real parent only when the
1849 whole multithreaded process exits).
1850 If the tracer and the real parent are the same process,
1851 the report is sent only once.
1855 requests return the requested data (but see NOTES),
1856 while other requests return zero.
1858 On error, all requests return \-1, and
1860 is set appropriately.
1861 Since the value returned by a successful
1863 request may be \-1, the caller must clear
1865 before the call, and then check it afterward
1866 to determine whether or not an error occurred.
1870 (i386 only) There was an error with allocating or freeing a debug register.
1873 There was an attempt to read from or write to an invalid area in
1874 the tracer's or the tracee's memory,
1875 probably because the area wasn't mapped or accessible.
1876 Unfortunately, under Linux, different variations of this fault
1881 more or less arbitrarily.
1884 An attempt was made to set an invalid option.
1888 is invalid, or an attempt was made to read from or
1889 write to an invalid area in the tracer's or the tracee's memory,
1890 or there was a word-alignment violation,
1891 or an invalid signal was specified during a restart request.
1894 The specified process cannot be traced.
1895 This could be because the
1896 tracer has insufficient privileges (the required capability is
1897 .BR CAP_SYS_PTRACE );
1898 unprivileged processes cannot trace processes that they
1899 cannot send signals to or those running
1900 set-user-ID/set-group-ID programs, for obvious reasons.
1901 Alternatively, the process may already be being traced,
1902 or (on kernels before 2.6.26) be
1907 The specified process does not exist, or is not currently being traced
1908 by the caller, or is not stopped
1909 (for requests that require a stopped tracee).
1913 Although arguments to
1915 are interpreted according to the prototype given,
1916 glibc currently declares
1918 as a variadic function with only the
1921 It is recommended to always supply four arguments,
1922 even if the requested operation does not use them,
1923 setting unused/ignored arguments to
1928 In Linux kernels before 2.6.26,
1929 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
1931 the process with PID 1, may not be traced.
1933 The layout of the contents of memory and the USER area are
1934 quite operating-system- and architecture-specific.
1935 The offset supplied, and the data returned,
1936 might not entirely match with the definition of
1938 .\" See http://lkml.org/lkml/2008/5/8/375
1940 The size of a "word" is determined by the operating-system variant
1941 (e.g., for 32-bit Linux it is 32 bits).
1943 This page documents the way the
1945 call works currently in Linux.
1946 Its behavior differs significantly on other flavors of UNIX.
1949 is highly specific to the operating system and architecture.
1950 .SS C library/kernel ABI differences
1951 At the system call level, the
1952 .BR PTRACE_PEEKTEXT ,
1953 .BR PTRACE_PEEKDATA ,
1956 requests have a different API: they store the result
1957 at the address specified by the
1959 parameter, and the return value is the error flag.
1960 The glibc wrapper function provides the API given in DESCRIPTION above,
1961 with the result being returned via the function return value.
1963 On hosts with 2.6 kernel headers,
1964 .B PTRACE_SETOPTIONS
1965 is declared with a different value than the one for 2.4.
1966 This leads to applications compiled with 2.6 kernel
1967 headers failing when run on 2.4 kernels.
1968 This can be worked around by redefining
1969 .B PTRACE_SETOPTIONS
1971 .BR PTRACE_OLDSETOPTIONS ,
1974 Group-stop notifications are sent to the tracer, but not to real parent.
1975 Last confirmed on 2.6.38.6.
1977 If a thread group leader is traced and exits by calling
1979 .\" Note from Denys Vlasenko:
1980 .\" Here "exits" means any kind of death - _exit, exit_group,
1981 .\" signal death. Signal death and exit_group cases are trivial,
1982 .\" though: since signal death and exit_group kill all other threads
1983 .\" too, "until all other threads exit" thing happens rather soon
1984 .\" in these cases. Therefore, only _exit presents observably
1985 .\" puzzling behavior to ptrace users: thread leader _exit's,
1986 .\" but WIFEXITED isn't reported! We are trying to explain here
1989 .B PTRACE_EVENT_EXIT
1990 stop will happen for it (if requested), but the subsequent
1992 notification will not be delivered until all other threads exit.
1993 As explained above, if one of other threads calls
1995 the death of the thread group leader will
1998 If the execed thread is not traced by this tracer,
1999 the tracer will never know that
2002 One possible workaround is to
2004 the thread group leader instead of restarting it in this case.
2005 Last confirmed on 2.6.38.6.
2006 .\" FIXME . need to test/verify this scenario
2010 signal may still cause a
2011 .B PTRACE_EVENT_EXIT
2012 stop before actual signal death.
2013 This may be changed in the future;
2015 is meant to always immediately kill tasks even under ptrace.
2016 Last confirmed on 2.6.38.6.
2018 Some system calls return with
2020 if a signal was sent to a tracee, but delivery was suppressed by the tracer.
2021 (This is very typical operation: it is usually
2022 done by debuggers on every attach, in order to not introduce
2025 As of Linux 3.2.9, the following system calls are affected
2026 (this list is likely incomplete):
2033 The usual symptom of this bug is that when you attach to
2034 a quiescent process with the command
2036 strace \-p <process-ID>
2038 then, instead of the usual
2039 and expected one-line output such as
2042 restart_syscall(<... resuming interrupted call ...>_
2048 select(6, [5], NULL, [5], NULL_
2051 ('_' denotes the cursor position), you observe more than one line.
2055 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
2059 What is not visible here is that the process was blocked in
2066 to return to user space with the error
2068 In this particular case, the program reacted to
2070 by checking the current time, and then executing
2073 (Programs which do not expect such "stray"
2075 errors may behave in an unintended way upon an
2090 .BR capabilities (7),
2093 This page is part of release 3.77 of the Linux
2096 A description of the project,
2097 information about reporting bugs,
2098 and the latest version of this page,
2100 \%http://www.kernel.org/doc/man\-pages/.