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>
43 .\" 2015-01, Kees Cook <keescook@chromium.org>
44 .\" Added PTRACE_O_TRACESECCOMP, PTRACE_EVENT_SECCOMP
46 .TH PTRACE 2 2015-07-23 "Linux" "Linux Programmer's Manual"
48 ptrace \- process trace
51 .B #include <sys/ptrace.h>
53 .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
54 .BI " void *" addr ", void *" data );
59 system call provides a means by which one process (the "tracer")
60 may observe and control the execution of another process (the "tracee"),
61 and examine and change the tracee's memory and registers.
62 It is primarily used to implement breakpoint debugging and system
65 A tracee first needs to be attached to the tracer.
66 Attachment and subsequent commands are per thread:
67 in a multithreaded process,
68 every thread can be individually attached to a
69 (potentially different) tracer,
70 or left not attached and thus not debugged.
71 Therefore, "tracee" always means "(one) thread",
72 never "a (possibly multithreaded) process".
73 Ptrace commands are always sent to
74 a specific tracee using a call of the form
76 ptrace(PTRACE_foo, pid, ...)
80 is the thread ID of the corresponding Linux thread.
82 (Note that in this page, a "multithreaded process"
83 means a thread group consisting of threads created using the
88 A process can initiate a trace by calling
90 and having the resulting child do a
92 followed (typically) by an
94 Alternatively, one process may commence tracing another process using
99 While being traced, the tracee will stop each time a signal is delivered,
100 even if the signal is being ignored.
103 which has its usual effect.)
104 The tracer will be notified at its next call to
106 (or one of the related "wait" system calls); that call will return a
108 value containing information that indicates
109 the cause of the stop in the tracee.
110 While the tracee is stopped,
111 the tracer can use various ptrace requests to inspect and modify the tracee.
112 The tracer then causes the tracee to continue,
113 optionally ignoring the delivered signal
114 (or even delivering a different signal instead).
117 .B PTRACE_O_TRACEEXEC
118 option is not in effect, all successful calls to
120 by the traced process will cause it to be sent a
123 giving the parent a chance to gain control before the new program
126 When the tracer is finished tracing, it can cause the tracee to continue
127 executing in a normal, untraced mode via
132 determines the action to be performed:
135 Indicate that this process is to be traced by its parent.
136 A process probably shouldn't make this request if its parent
137 isn't expecting to trace it.
146 request is used only by the tracee;
147 the remaining requests are used only by the tracer.
148 In the following requests,
150 specifies the thread ID of the tracee to be acted on.
151 For requests other than
154 .BR PTRACE_INTERRUPT ,
157 the tracee must be stopped.
159 .BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA
160 Read a word at the address
162 in the tracee's memory, returning the word as the result of the
165 Linux does not have separate text and data address spaces,
166 so these two requests are currently equivalent.
168 is ignored; but see NOTES.)
171 .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
172 .\" and that is the name that seems common on other systems.
173 Read a word at offset
175 in the tracee's USER area,
176 which holds the registers and other information about the process
179 The word is returned as the result of the
182 Typically, the offset must be word-aligned, though this might vary by
186 is ignored; but see NOTES.)
188 .BR PTRACE_POKETEXT ", " PTRACE_POKEDATA
193 in the tracee's memory.
197 .BR PTRACE_PEEKDATA ,
198 these two requests are currently equivalent.
201 .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
202 .\" and that is the name that seems common on other systems.
207 in the tracee's USER area.
209 .BR PTRACE_PEEKUSER ,
210 the offset must typically be word-aligned.
211 In order to maintain the integrity of the kernel,
212 some modifications to the USER area are disallowed.
213 .\" FIXME In the preceding sentence, which modifications are disallowed,
214 .\" and when they are disallowed, how does user space discover that fact?
216 .BR PTRACE_GETREGS ", " PTRACE_GETFPREGS
217 Copy the tracee's general-purpose or floating-point registers,
218 respectively, to the address
223 for information on the format of this data.
226 Note that SPARC systems have the meaning of
232 is ignored and the registers are copied to the address
237 are not present on all architectures.
239 .BR PTRACE_GETREGSET " (since Linux 2.6.34)"
240 Read the tracee's registers.
242 specifies, in an architecture-dependent way, the type of registers to be read.
244 (with numerical value 1)
245 usually results in reading of general-purpose registers.
246 If the CPU has, for example,
247 floating-point and/or vector registers, they can be retrieved by setting
255 which describes the destination buffer's location and length.
256 On return, the kernel modifies
258 to indicate the actual number of bytes returned.
260 .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
261 Modify the tracee's general-purpose or floating-point registers,
262 respectively, from the address
266 .BR PTRACE_POKEUSER ,
267 some general-purpose register modifications may be disallowed.
268 .\" FIXME . In the preceding sentence, which modifications are disallowed,
269 .\" and when they are disallowed, how does user space discover that fact?
272 Note that SPARC systems have the meaning of
278 is ignored and the registers are copied from the address
283 are not present on all architectures.
285 .BR PTRACE_SETREGSET " (since Linux 2.6.34)"
286 Modify the tracee's registers.
292 .BR PTRACE_GETREGSET .
294 .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
295 Retrieve information about the signal that caused the stop.
300 from the tracee to the address
306 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
307 Set signal information:
310 structure from the address
312 in the tracer to the tracee.
313 This will affect only signals that would normally be delivered to
314 the tracee and were caught by the tracer.
315 It may be difficult to tell
316 these normal signals from synthetic signals generated by
322 .BR PTRACE_PEEKSIGINFO " (since Linux 3.10)"
323 .\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4
326 structures without removing signals from a queue.
329 .I ptrace_peeksiginfo_args
330 structure that specifies the ordinal position from which
331 copying of signals should start,
332 and the number of signals to copy.
334 structures are copied into the buffer pointed to by
336 The return value contains the number of copied signals (zero indicates
337 that there is no signal corresponding to the specified ordinal position).
343 field includes information
346 etc.) that are not otherwise exposed to user space.
350 struct ptrace_peeksiginfo_args {
351 u64 off; /* Ordinal position in queue at which
352 to start copying signals */
353 u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */
354 s32 nr; /* Number of signals to copy */
358 Currently, there is only one flag,
359 .BR PTRACE_PEEKSIGINFO_SHARED ,
360 for dumping signals from the process-wide signal queue.
361 If this flag is not set,
362 signals are read from the per-thread queue of the specified thread.
366 .BR PTRACE_GETSIGMASK " (since Linux 3.11)"
367 .\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
368 Place a copy of the mask of blocked signals (see
370 in the buffer pointed to by
372 which should be a pointer to a buffer of type
376 argument contains the size of the buffer pointed to by
379 .IR sizeof(sigset_t) ).
381 .BR PTRACE_SETSIGMASK " (since Linux 3.11)"
382 Change the mask of blocked signals (see
384 to the value specified in the buffer pointed to by
386 which should be a pointer to a buffer of type
390 argument contains the size of the buffer pointed to by
393 .IR sizeof(sigset_t) ).
395 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
396 Set ptrace options from
401 is interpreted as a bit mask of options,
402 which are specified by the following flags:
405 .BR PTRACE_O_EXITKILL " (since Linux 3.8)"
406 .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123
407 If a tracer sets this flag, a
409 signal will be sent to every tracee if the tracer exits.
410 This option is useful for ptrace jailers that
411 want to ensure that tracees can never escape the tracer's control.
413 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
414 Stop the tracee at the next
416 and automatically start tracing the newly cloned process,
417 which will start with a
426 by the tracer will return a
431 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
434 The PID of the new process can be retrieved with
435 .BR PTRACE_GETEVENTMSG .
437 This option may not catch
445 .B PTRACE_EVENT_VFORK
446 will be delivered instead
448 .B PTRACE_O_TRACEVFORK
449 is set; otherwise if the tracee calls
451 with the exit signal set to
455 .B PTRACE_O_TRACEFORK
458 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
459 Stop the tracee at the next
463 by the tracer will return a
468 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
471 If the execing thread is not a thread group leader,
472 the thread ID is reset to thread group leader's ID before this stop.
473 Since Linux 3.0, the former thread ID can be retrieved with
474 .BR PTRACE_GETEVENTMSG .
476 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
477 Stop the tracee at exit.
480 by the tracer will return a
485 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
488 The tracee's exit status can be retrieved with
489 .BR PTRACE_GETEVENTMSG .
491 The tracee is stopped early during process exit,
492 when registers are still available,
493 allowing the tracer to see where the exit occurred,
494 whereas the normal exit notification is done after the process
496 Even though context is available,
497 the tracer cannot prevent the exit from happening at this point.
499 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
500 Stop the tracee at the next
502 and automatically start tracing the newly forked process,
503 which will start with a
512 by the tracer will return a
517 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
520 The PID of the new process can be retrieved with
521 .BR PTRACE_GETEVENTMSG .
523 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
524 When delivering system call traps, set bit 7 in the signal number
526 .IR "SIGTRAP|0x80" ).
527 This makes it easy for the tracer to distinguish
528 normal traps from those caused by a system call.
529 .RB ( PTRACE_O_TRACESYSGOOD
530 may not work on all architectures.)
532 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
533 Stop the tracee at the next
535 and automatically start tracing the newly vforked process,
536 which will start with a
545 by the tracer will return a
550 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
553 The PID of the new process can be retrieved with
554 .BR PTRACE_GETEVENTMSG .
556 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
557 Stop the tracee at the completion of the next
561 by the tracer will return a
566 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
569 The PID of the new process can (since Linux 2.6.18) be retrieved with
570 .BR PTRACE_GETEVENTMSG .
572 .BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)"
573 Stop the tracee when a
575 .BR SECCOMP_RET_TRACE
579 by the tracer will return a
584 status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8))
587 While this triggers a
589 stop, it is similar to a syscall-enter-stop, in that the tracee has
590 not yet entered the syscall that seccomp triggered on.
591 The seccomp event message data (from the
593 portion of the seccomp filter rule) can be retrieved with
594 .BR PTRACE_GETEVENTMSG .
597 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
598 Retrieve a message (as an
599 .IR "unsigned long" )
600 about the ptrace event
601 that just happened, placing it at the address
605 .BR PTRACE_EVENT_EXIT ,
606 this is the tracee's exit status.
608 .BR PTRACE_EVENT_FORK ,
609 .BR PTRACE_EVENT_VFORK ,
610 .BR PTRACE_EVENT_VFORK_DONE ,
612 .BR PTRACE_EVENT_CLONE ,
613 this is the PID of the new process.
615 .BR PTRACE_EVENT_SECCOMP ,
620 associated with the triggered rule.
625 Restart the stopped tracee process.
629 it is interpreted as the number of a signal to be delivered to the tracee;
630 otherwise, no signal is delivered.
631 Thus, for example, the tracer can control
632 whether a signal sent to the tracee is delivered or not.
636 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
637 Restart the stopped tracee as for
639 but arrange for the tracee to be stopped at
640 the next entry to or exit from a system call,
641 or after execution of a single instruction, respectively.
642 (The tracee will also, as usual, be stopped upon receipt of a signal.)
643 From the tracer's perspective, the tracee will appear to have been
644 stopped by receipt of a
648 for example, the idea is to inspect
649 the arguments to the system call at the first stop,
652 and inspect the return value of the system call at the second stop.
655 argument is treated as for
660 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
663 continue and stop on entry to the next system call,
664 which will not be executed.
666 .BR PTRACE_SYSEMU_SINGLESTEP ,
667 do the same but also singlestep if not a system call.
668 This call is used by programs like
669 User Mode Linux that want to emulate all the tracee's system calls.
672 argument is treated as for
677 These requests are currently
679 supported only on x86.
681 .BR PTRACE_LISTEN " (since Linux 3.4)"
682 Restart the stopped tracee, but prevent it from executing.
683 The resulting state of the tracee is similar to a process which
684 has been stopped by a
686 (or other stopping signal).
687 See the "group-stop" subsection for additional information.
689 works only on tracees attached by
701 .I This operation is deprecated; do not use it!
710 is that it requires the tracee to be in signal-delivery-stop,
711 otherwise it may not work
712 (i.e., may complete successfully but won't kill the tracee).
713 By contrast, sending a
715 directly has no such limitation.
716 .\" [Note from Denys Vlasenko:
717 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
718 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
720 .BR PTRACE_INTERRUPT " (since Linux 3.4)"
722 If the tracee is running or sleeping in kernel space and
725 the system call is interrupted and syscall-exit-stop is reported.
726 (The interrupted system call is restarted when the tracee is restarted.)
727 If the tracee was already stopped by a signal and
730 the tracee stops with
734 returns the stop signal.
735 If any other ptrace-stop is generated at the same time (for example,
736 if a signal is sent to the tracee), this ptrace-stop happens.
737 If none of the above applies (for example, if the tracee is running in user
738 space), it stops with
745 only works on tracees attached by
749 Attach to the process specified in
751 making it a tracee of the calling process.
752 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
753 .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
754 .\" Basically, it's not true for any Linux in practical use.
755 .\" ; the behavior of the tracee is as if it had done a
756 .\" .BR PTRACE_TRACEME .
757 .\" The calling process actually becomes the parent of the tracee
758 .\" process for most purposes (e.g., it will receive
759 .\" notification of tracee events and appears in
761 .\" output as the tracee's parent), but a
763 .\" by the tracee will still return the PID of the original parent.
766 but will not necessarily have stopped
767 by the completion of this call; use
769 to wait for the tracee to stop.
770 See the "Attaching and detaching" subsection for additional information.
776 .BR PTRACE_SEIZE " (since Linux 3.4)"
777 Attach to the process specified in
779 making it a tracee of the calling process.
783 does not stop the process.
784 Group-stops are reported as
788 returns the stop signal.
789 Automatically attached children stop with
797 signal delivered to them.
799 does not deliver an extra
808 The "seized" behavior just described is inherited by
809 children that are automatically attached using
810 .BR PTRACE_O_TRACEFORK ,
811 .BR PTRACE_O_TRACEVFORK ,
813 .BR PTRACE_O_TRACECLONE .
817 contains a bit mask of ptrace options to activate immediately.
820 Restart the stopped tracee as for
822 but first detach from it.
823 Under Linux, a tracee can be detached in this way regardless
824 of which method was used to initiate tracing.
827 .SS Death under ptrace
828 When a (possibly multithreaded) process receives a killing signal
829 (one whose disposition is set to
831 and whose default action is to kill the process),
833 Tracees report their death to their tracer(s).
834 Notification of this event is delivered via
837 Note that the killing signal will first cause signal-delivery-stop
838 (on one tracee only),
839 and only after it is injected by the tracer
840 (or after it was dispatched to a thread which isn't traced),
841 will death from the signal happen on
843 tracees within a multithreaded process.
844 (The term "signal-delivery-stop" is explained below.)
847 does not generate signal-delivery-stop and
848 therefore the tracer can't suppress it.
850 kills even within system calls
851 (syscall-exit-stop is not generated prior to death by
853 The net effect is that
855 always kills the process (all its threads),
856 even if some threads of the process are ptraced.
858 When the tracee calls
860 it reports its death to its tracer.
861 Other threads are not affected.
863 When any thread executes
865 every tracee in its thread group reports its death to its tracer.
868 .B PTRACE_O_TRACEEXIT
871 will happen before actual death.
872 This applies to exits via
875 and signal deaths (except
877 depending on the kernel version; see BUGS below),
878 and when threads are torn down on
880 in a multithreaded process.
882 The tracer cannot assume that the ptrace-stopped tracee exists.
883 There are many scenarios when the tracee may die while stopped (such as
885 Therefore, the tracer must be prepared to handle an
887 error on any ptrace operation.
888 Unfortunately, the same error is returned if the tracee
889 exists but is not ptrace-stopped
890 (for commands which require a stopped tracee),
891 or if it is not traced by the process which issued the ptrace call.
892 The tracer needs to keep track of the stopped/running state of the tracee,
895 as "tracee died unexpectedly" only if it knows that the tracee has
896 been observed to enter ptrace-stop.
897 Note that there is no guarantee that
899 will reliably report the tracee's death status if a
900 ptrace operation returned
903 may return 0 instead.
904 In other words, the tracee may be "not yet fully dead",
905 but already refusing ptrace requests.
907 The tracer can't assume that the tracee
909 ends its life by reporting
912 .IR WIFSIGNALED(status) ;
913 there are cases where this does not occur.
914 For example, if a thread other than thread group leader does an
917 its PID will never be seen again,
918 and any subsequent ptrace stops will be reported under
919 the thread group leader's PID.
921 A tracee can be in two states: running or stopped.
922 For the purposes of ptrace, a tracee which is blocked in a system call
927 is nevertheless considered to be running, even if the tracee is blocked
929 The state of the tracee after
931 is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
932 won't work on it, and it will deliver
935 but it also may be considered "stopped" because
936 it is not executing instructions (is not scheduled), and if it was
939 it will not respond to signals until
943 There are many kinds of states when the tracee is stopped, and in ptrace
944 discussions they are often conflated.
945 Therefore, it is important to use precise terms.
947 In this manual page, any stopped state in which the tracee is ready
948 to accept ptrace commands from the tracer is called
951 be further subdivided into
952 .IR signal-delivery-stop ,
956 These stopped states are described in detail below.
958 When the running tracee enters ptrace-stop, it notifies its tracer using
960 (or one of the other "wait" system calls).
961 Most of this manual page assumes that the tracer waits with:
963 pid = waitpid(pid_or_minus_1, &status, __WALL);
965 Ptrace-stopped tracees are reported as returns with
968 .I WIFSTOPPED(status)
971 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
972 .\" I am not 100% sure there aren't ugly corner cases.) Are the
973 .\" rules different if user wants to use waitid? Will waitid require
979 flag does not include the
983 flags, but implies their functionality.
989 is not recommended: the "continued" state is per-process and
990 consuming it can confuse the real parent of the tracee.
996 to return 0 ("no wait results available yet")
997 even if the tracer knows there should be a notification.
1002 ptrace(PTRACE_CONT, pid, 0L, 0L);
1003 if (errno == ESRCH) {
1004 /* tracee is dead */
1005 r = waitpid(tracee, &status, __WALL | WNOHANG);
1006 /* r can still be 0 here! */
1010 .\" waitid usage? WNOWAIT?
1011 .\" describe how wait notifications queue (or not queue)
1013 The following kinds of ptrace-stops exist: signal-delivery-stops,
1016 stops, syscall-stops.
1017 They all are reported by
1020 .I WIFSTOPPED(status)
1022 They may be differentiated by examining the value
1024 and if there is ambiguity in that value, by querying
1025 .BR PTRACE_GETSIGINFO .
1028 macro can't be used to perform this examination,
1029 because it returns the value
1030 .IR "(status>>8)\ &\ 0xff" .)
1031 .SS Signal-delivery-stop
1032 When a (possibly multithreaded) process receives any signal except
1034 the kernel selects an arbitrary thread which handles the signal.
1035 (If the signal is generated with
1037 the target thread can be explicitly selected by the caller.)
1038 If the selected thread is traced, it enters signal-delivery-stop.
1039 At this point, the signal is not yet delivered to the process,
1040 and can be suppressed by the tracer.
1041 If the tracer doesn't suppress the signal,
1042 it passes the signal to the tracee in the next ptrace restart request.
1043 This second step of signal delivery is called
1044 .I "signal injection"
1045 in this manual page.
1046 Note that if the signal is blocked,
1047 signal-delivery-stop doesn't happen until the signal is unblocked,
1048 with the usual exception that
1052 Signal-delivery-stop is observed by the tracer as
1055 .I WIFSTOPPED(status)
1056 true, with the signal returned by
1057 .IR WSTOPSIG(status) .
1060 this may be a different kind of ptrace-stop;
1061 see the "Syscall-stops" and "execve" sections below for details.
1064 returns a stopping signal, this may be a group-stop; see below.
1065 .SS Signal injection and suppression
1066 After signal-delivery-stop is observed by the tracer,
1067 the tracer should restart the tracee with the call
1069 ptrace(PTRACE_restart, pid, 0, sig)
1073 is one of the restarting ptrace requests.
1076 is 0, then a signal is not delivered.
1077 Otherwise, the signal
1080 This operation is called
1081 .I "signal injection"
1082 in this manual page, to distinguish it from signal-delivery-stop.
1086 value may be different from the
1088 value: the tracer can cause a different signal to be injected.
1090 Note that a suppressed signal still causes system calls to return
1092 In this case, system calls will be restarted: the tracer will
1093 observe the tracee to reexecute the interrupted system call (or
1094 .BR restart_syscall (2)
1095 system call for a few system calls which use a different mechanism
1096 for restarting) if the tracer uses
1097 .BR PTRACE_SYSCALL .
1098 Even system calls (such as
1100 which are not restartable after signal are restarted after
1101 signal is suppressed;
1102 however, kernel bugs exist which cause some system calls to fail with
1104 even though no observable signal is injected to the tracee.
1106 Restarting ptrace commands issued in ptrace-stops other than
1107 signal-delivery-stop are not guaranteed to inject a signal, even if
1110 No error is reported; a nonzero
1112 may simply be ignored.
1113 Ptrace users should not try to "create a new signal" this way: use
1117 The fact that signal injection requests may be ignored
1118 when restarting the tracee after
1119 ptrace stops that are not signal-delivery-stops
1120 is a cause of confusion among ptrace users.
1121 One typical scenario is that the tracer observes group-stop,
1122 mistakes it for signal-delivery-stop, restarts the tracee with
1124 ptrace(PTRACE_restart, pid, 0, stopsig)
1126 with the intention of injecting
1130 gets ignored and the tracee continues to run.
1134 signal has a side effect of waking up (all threads of)
1135 a group-stopped process.
1136 This side effect happens before signal-delivery-stop.
1137 The tracer can't suppress this side effect (it can
1138 only suppress signal injection, which only causes the
1140 handler to not be executed in the tracee, if such a handler is installed).
1141 In fact, waking up from group-stop may be followed by
1142 signal-delivery-stop for signal(s)
1145 if they were pending when
1150 may be not the first signal observed by the tracee after it was sent.
1152 Stopping signals cause (all threads of) a process to enter group-stop.
1153 This side effect happens after signal injection, and therefore can be
1154 suppressed by the tracer.
1156 In Linux 2.4 and earlier, the
1158 signal can't be injected.
1159 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
1162 .\" /* The debugger continued. Ignore SIGSTOP. */
1163 .\" if (signr == SIGSTOP)
1166 .B PTRACE_GETSIGINFO
1167 can be used to retrieve a
1169 structure which corresponds to the delivered signal.
1170 .B PTRACE_SETSIGINFO
1171 may be used to modify it.
1173 .B PTRACE_SETSIGINFO
1174 has been used to alter
1180 parameter in the restarting command must match,
1181 otherwise the result is undefined.
1183 When a (possibly multithreaded) process receives a stopping signal,
1185 If some threads are traced, they enter a group-stop.
1186 Note that the stopping signal will first cause signal-delivery-stop
1187 (on one tracee only), and only after it is injected by the tracer
1188 (or after it was dispatched to a thread which isn't traced),
1189 will group-stop be initiated on
1191 tracees within the multithreaded process.
1192 As usual, every tracee reports its group-stop separately
1193 to the corresponding tracer.
1195 Group-stop is observed by the tracer as
1198 .I WIFSTOPPED(status)
1199 true, with the stopping signal available via
1200 .IR WSTOPSIG(status) .
1201 The same result is returned by some other classes of ptrace-stops,
1202 therefore the recommended practice is to perform the call
1204 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
1206 The call can be avoided if the signal is not
1212 only these four signals are stopping signals.
1213 If the tracer sees something else, it can't be a group-stop.
1214 Otherwise, the tracer needs to call
1215 .BR PTRACE_GETSIGINFO .
1217 .B PTRACE_GETSIGINFO
1220 then it is definitely a group-stop.
1221 (Other failure codes are possible, such as
1223 ("no such process") if a
1227 If tracee was attached using
1229 group-stop is indicated by
1230 .BR PTRACE_EVENT_STOP :
1231 .IR "status>>16 == PTRACE_EVENT_STOP" .
1232 This allows detection of group-stops
1233 without requiring an extra
1234 .B PTRACE_GETSIGINFO
1238 after the tracer sees the tracee ptrace-stop and until it
1239 restarts or kills it, the tracee will not run,
1240 and will not send notifications (except
1242 death) to the tracer, even if the tracer enters into another
1246 The kernel behavior described in the previous paragraph
1247 causes a problem with transparent handling of stopping signals.
1248 If the tracer restarts the tracee after group-stop,
1250 is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
1251 If the tracer doesn't restart the tracee before entering into the next
1255 signals will not be reported to the tracer;
1256 this would cause the
1258 signals to have no effect on the tracee.
1260 Since Linux 3.4, there is a method to overcome this problem: instead of
1264 command can be used to restart a tracee in a way where it does not execute,
1265 but waits for a new event which it can report via
1268 it is restarted by a
1270 .SS PTRACE_EVENT stops
1273 options, the tracee will enter ptrace-stops called
1278 stops are observed by the tracer as
1281 .IR WIFSTOPPED(status) ,
1286 An additional bit is set in the higher byte of the status word:
1291 (SIGTRAP | PTRACE_EVENT_foo << 8).
1293 The following events exist:
1295 .B PTRACE_EVENT_VFORK
1296 Stop before return from
1303 When the tracee is continued after this stop, it will wait for child to
1304 exit/exec before continuing its execution
1305 (in other words, the usual behavior on
1308 .B PTRACE_EVENT_FORK
1309 Stop before return from
1313 with the exit signal set to
1316 .B PTRACE_EVENT_CLONE
1317 Stop before return from
1320 .B PTRACE_EVENT_VFORK_DONE
1321 Stop before return from
1328 but after the child unblocked this tracee by exiting or execing.
1330 For all four stops described above,
1331 the stop occurs in the parent (i.e., the tracee),
1332 not in the newly created thread.
1333 .BR PTRACE_GETEVENTMSG
1334 can be used to retrieve the new thread's ID.
1336 .B PTRACE_EVENT_EXEC
1337 Stop before return from
1340 .BR PTRACE_GETEVENTMSG
1341 returns the former thread ID.
1343 .B PTRACE_EVENT_EXIT
1344 Stop before exit (including death from
1345 .BR exit_group (2)),
1346 signal death, or exit caused by
1348 in a multithreaded process.
1349 .B PTRACE_GETEVENTMSG
1350 returns the exit status.
1351 Registers can be examined
1352 (unlike when "real" exit happens).
1353 The tracee is still alive; it needs to be
1356 .BR PTRACE_DETACH ed
1359 .B PTRACE_EVENT_STOP
1362 command, or group-stop, or initial ptrace-stop when a new child is attached
1363 (only if attached using
1366 .B PTRACE_EVENT_SECCOMP
1369 rule on tracee syscall entry when
1370 .BR PTRACE_O_TRACESECCOMP
1371 has been set by the tracer.
1372 The seccomp event message data (from the
1373 .BR SECCOMP_RET_DATA
1374 portion of the seccomp filter rule) can be retrieved with
1375 .BR PTRACE_GETEVENTMSG .
1377 .B PTRACE_GETSIGINFO
1387 .IR "(event<<8)\ |\ SIGTRAP" .
1389 If the tracee was restarted by
1390 .BR PTRACE_SYSCALL ,
1392 syscall-enter-stop just prior to entering any system call.
1393 If the tracer restarts the tracee with
1394 .BR PTRACE_SYSCALL ,
1395 the tracee enters syscall-exit-stop when the system call is finished,
1396 or if it is interrupted by a signal.
1397 (That is, signal-delivery-stop never happens between syscall-enter-stop
1398 and syscall-exit-stop; it happens
1402 Other possibilities are that the tracee may stop in a
1404 stop, exit (if it entered
1407 .BR exit_group (2)),
1410 or die silently (if it is a thread group leader, the
1412 happened in another thread,
1413 and that thread is not traced by the same tracer;
1414 this situation is discussed later).
1416 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1419 .I WIFSTOPPED(status)
1425 .B PTRACE_O_TRACESYSGOOD
1426 option was set by the tracer, then
1429 .IR "(SIGTRAP\ |\ 0x80)" .
1431 Syscall-stops can be distinguished from signal-delivery-stop with
1434 .BR PTRACE_GETSIGINFO
1435 for the following cases:
1439 was delivered as a result of a user-space action,
1440 for example, a system call
1445 expiration of a POSIX timer,
1446 change of state on a POSIX message queue,
1447 or completion of an asynchronous I/O request.
1449 .IR si_code " == SI_KERNEL (0x80)"
1451 was sent by the kernel.
1453 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1454 This is a syscall-stop.
1456 However, syscall-stops happen very often (twice per system call),
1458 .B PTRACE_GETSIGINFO
1459 for every syscall-stop may be somewhat expensive.
1461 Some architectures allow the cases to be distinguished
1462 by examining registers.
1463 For example, on x86,
1467 in syscall-enter-stop.
1470 (like any other signal) always happens
1475 almost never contains
1479 looks like "syscall-stop which is not syscall-enter-stop";
1480 in other words, it looks like a
1481 "stray syscall-exit-stop" and can be detected this way.
1482 But such detection is fragile and is best avoided.
1485 .B PTRACE_O_TRACESYSGOOD
1486 option is the recommended method to distinguish syscall-stops
1487 from other kinds of ptrace-stops,
1488 since it is reliable and does not incur a performance penalty.
1490 Syscall-enter-stop and syscall-exit-stop are
1491 indistinguishable from each other by the tracer.
1492 The tracer needs to keep track of the sequence of
1493 ptrace-stops in order to not misinterpret syscall-enter-stop as
1494 syscall-exit-stop or vice versa.
1495 The rule is that syscall-enter-stop is
1496 always followed by syscall-exit-stop,
1498 stop or the tracee's death;
1499 no other kinds of ptrace-stop can occur in between.
1501 If after syscall-enter-stop,
1502 the tracer uses a restarting command other than
1503 .BR PTRACE_SYSCALL ,
1504 syscall-exit-stop is not generated.
1506 .B PTRACE_GETSIGINFO
1507 on syscall-stops returns
1516 .IR (SIGTRAP|0x80) .
1517 .SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops
1518 [Details of these kinds of stops are yet to be documented.]
1521 .\" document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
1522 .\" PTRACE_SYSEMU_SINGLESTEP
1523 .SS Informational and restarting ptrace commands
1524 Most ptrace commands (all except
1527 .BR PTRACE_TRACEME ,
1528 .BR PTRACE_INTERRUPT ,
1531 require the tracee to be in a ptrace-stop, otherwise they fail with
1534 When the tracee is in ptrace-stop,
1535 the tracer can read and write data to
1536 the tracee using informational commands.
1537 These commands leave the tracee in ptrace-stopped state:
1540 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1541 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1542 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1543 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1544 ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
1545 ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
1546 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1547 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1548 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
1549 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1552 Note that some errors are not reported.
1553 For example, setting signal information
1555 may have no effect in some ptrace-stops, yet the call may succeed
1556 (return 0 and not set
1559 .B PTRACE_GETEVENTMSG
1560 may succeed and return some random value if current ptrace-stop
1561 is not documented as returning a meaningful event message.
1565 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1568 The tracee's current flags are replaced.
1569 Flags are inherited by new tracees created and "auto-attached" via active
1570 .BR PTRACE_O_TRACEFORK ,
1571 .BR PTRACE_O_TRACEVFORK ,
1573 .BR PTRACE_O_TRACECLONE
1576 Another group of commands makes the ptrace-stopped tracee run.
1579 ptrace(cmd, pid, 0, sig);
1587 .BR PTRACE_SYSCALL ,
1588 .BR PTRACE_SINGLESTEP ,
1591 .BR PTRACE_SYSEMU_SINGLESTEP .
1592 If the tracee is in signal-delivery-stop,
1594 is the signal to be injected (if it is nonzero).
1598 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
1599 recommended practice is to always pass 0 in
1601 .SS Attaching and detaching
1602 A thread can be attached to the tracer using the call
1604 ptrace(PTRACE_ATTACH, pid, 0, 0);
1608 ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
1614 If the tracer wants this
1616 to have no effect, it needs to suppress it.
1617 Note that if other signals are concurrently sent to
1618 this thread during attach,
1619 the tracer may see the tracee enter signal-delivery-stop
1620 with other signal(s) first!
1621 The usual practice is to reinject these signals until
1623 is seen, then suppress
1626 The design bug here is that a ptrace attach and a concurrently delivered
1628 may race and the concurrent
1632 .\" FIXME . Describe how to attach to a thread which is already group-stopped.
1634 Since attaching sends
1636 and the tracer usually suppresses it, this may cause a stray
1638 return from the currently executing system call in the tracee,
1639 as described in the "Signal injection and suppression" section.
1643 can be used instead of
1646 does not stop the attached process.
1648 it after attach (or at any other time) without sending it any signals,
1655 ptrace(PTRACE_TRACEME, 0, 0, 0);
1657 turns the calling thread into a tracee.
1658 The thread continues to run (doesn't enter ptrace-stop).
1659 A common practice is to follow the
1665 and allow the parent (which is our tracer now) to observe our
1666 signal-delivery-stop.
1669 .BR PTRACE_O_TRACEFORK ,
1670 .BR PTRACE_O_TRACEVFORK ,
1672 .BR PTRACE_O_TRACECLONE
1673 options are in effect, then children created by, respectively,
1683 with the exit signal set to
1687 are automatically attached to the same tracer which traced their parent.
1689 is delivered to the children, causing them to enter
1690 signal-delivery-stop after they exit the system call which created them.
1692 Detaching of the tracee is performed by:
1694 ptrace(PTRACE_DETACH, pid, 0, sig);
1697 is a restarting operation;
1698 therefore it requires the tracee to be in ptrace-stop.
1699 If the tracee is in signal-delivery-stop, a signal can be injected.
1702 parameter may be silently ignored.
1704 If the tracee is running when the tracer wants to detach it,
1705 the usual solution is to send
1709 to make sure it goes to the correct thread),
1710 wait for the tracee to stop in signal-delivery-stop for
1712 and then detach it (suppressing
1715 A design bug is that this can race with concurrent
1717 Another complication is that the tracee may enter other ptrace-stops
1718 and needs to be restarted and waited for again, until
1721 Yet another complication is to be sure that
1722 the tracee is not already ptrace-stopped,
1723 because no signal delivery happens while it is\(emnot even
1725 .\" FIXME . Describe how to detach from a group-stopped tracee so that it
1726 .\" doesn't run, but continues to wait for SIGCONT.
1728 If the tracer dies, all tracees are automatically detached and restarted,
1729 unless they were in group-stop.
1730 Handling of restart from group-stop is currently buggy,
1731 but the "as planned" behavior is to leave tracee stopped and waiting for
1733 If the tracee is restarted from signal-delivery-stop,
1734 the pending signal is injected.
1735 .SS execve(2) under ptrace
1736 .\" clone(2) CLONE_THREAD says:
1737 .\" If any of the threads in a thread group performs an execve(2),
1738 .\" then all threads other than the thread group leader are terminated,
1739 .\" and the new program is executed in the thread group leader.
1741 When one thread in a multithreaded process calls
1743 the kernel destroys all other threads in the process,
1744 .\" In kernel 3.1 sources, see fs/exec.c::de_thread()
1745 and resets the thread ID of the execing thread to the
1746 thread group ID (process ID).
1747 (Or, to put things another way, when a multithreaded process does an
1749 at completion of the call, it appears as though the
1751 occurred in the thread group leader, regardless of which thread did the
1753 This resetting of the thread ID looks very confusing to tracers:
1755 All other threads stop in
1756 .B PTRACE_EVENT_EXIT
1758 .BR PTRACE_O_TRACEEXIT
1759 option was turned on.
1760 Then all other threads except the thread group leader report
1761 death as if they exited via
1765 The execing tracee changes its thread ID while it is in the
1767 (Remember, under ptrace, the "pid" returned from
1769 or fed into ptrace calls, is the tracee's thread ID.)
1770 That is, the tracee's thread ID is reset to be the same as its process ID,
1771 which is the same as the thread group leader's thread ID.
1774 .B PTRACE_EVENT_EXEC
1775 stop happens, if the
1776 .BR PTRACE_O_TRACEEXEC
1777 option was turned on.
1779 If the thread group leader has reported its
1780 .B PTRACE_EVENT_EXIT
1782 it appears to the tracer that
1783 the dead thread leader "reappears from nowhere".
1784 (Note: the thread group leader does not report death via
1785 .I WIFEXITED(status)
1786 until there is at least one other live thread.
1787 This eliminates the possibility that the tracer will see
1788 it dying and then reappearing.)
1789 If the thread group leader was still alive,
1790 for the tracer this may look as if thread group leader
1791 returns from a different system call than it entered,
1792 or even "returned from a system call even though
1793 it was not in any system call".
1794 If the thread group leader was not traced
1795 (or was traced by a different tracer), then during
1797 it will appear as if it has become a tracee of
1798 the tracer of the execing tracee.
1800 All of the above effects are the artifacts of
1801 the thread ID change in the tracee.
1804 .B PTRACE_O_TRACEEXEC
1805 option is the recommended tool for dealing with this situation.
1807 .BR PTRACE_EVENT_EXEC
1812 In this stop, the tracer can use
1813 .B PTRACE_GETEVENTMSG
1814 to retrieve the tracee's former thread ID.
1815 (This feature was introduced in Linux 3.0.)
1817 .B PTRACE_O_TRACEEXEC
1818 option disables legacy
1823 When the tracer receives
1824 .B PTRACE_EVENT_EXEC
1826 it is guaranteed that except this tracee and the thread group leader,
1827 no other threads from the process are alive.
1830 .B PTRACE_EVENT_EXEC
1832 the tracer should clean up all its internal
1833 data structures describing the threads of this process,
1834 and retain only one data structure\(emone which
1835 describes the single still running tracee, with
1837 thread ID == thread group ID == process ID.
1839 Example: two threads call
1844 *** we get syscall-enter-stop in thread 1: **
1845 PID1 execve("/bin/foo", "foo" <unfinished ...>
1846 *** we issue PTRACE_SYSCALL for thread 1 **
1847 *** we get syscall-enter-stop in thread 2: **
1848 PID2 execve("/bin/bar", "bar" <unfinished ...>
1849 *** we issue PTRACE_SYSCALL for thread 2 **
1850 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
1851 *** we get syscall-exit-stop for PID0: **
1852 PID0 <... execve resumed> ) = 0
1856 .B PTRACE_O_TRACEEXEC
1859 in effect for the execing tracee,
1860 and if the tracee was
1861 .BR PTRACE_ATTACH ed
1864 the kernel delivers an extra
1869 This is an ordinary signal (similar to one which can be
1872 not a special kind of ptrace-stop.
1874 .B PTRACE_GETSIGINFO
1875 for this signal returns
1879 This signal may be blocked by signal mask,
1880 and thus may be delivered (much) later.
1882 Usually, the tracer (for example,
1884 would not want to show this extra post-execve
1886 signal to the user, and would suppress its delivery to the tracee (if
1890 it is a killing signal).
1891 However, determining
1894 to suppress is not easy.
1896 .B PTRACE_O_TRACEEXEC
1899 and thus suppressing this extra
1901 is the recommended approach.
1903 The ptrace API (ab)uses the standard UNIX parent/child signaling over
1905 This used to cause the real parent of the process to stop receiving
1908 notifications when the child process is traced by some other process.
1910 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
1911 exist; see BUGS below.
1913 As of Linux 2.6.38, the following is believed to work correctly:
1915 exit/death by signal is reported first to the tracer, then,
1916 when the tracer consumes the
1918 result, to the real parent (to the real parent only when the
1919 whole multithreaded process exits).
1920 If the tracer and the real parent are the same process,
1921 the report is sent only once.
1925 requests return the requested data (but see NOTES),
1926 while other requests return zero.
1928 On error, all requests return \-1, and
1930 is set appropriately.
1931 Since the value returned by a successful
1933 request may be \-1, the caller must clear
1935 before the call, and then check it afterward
1936 to determine whether or not an error occurred.
1940 (i386 only) There was an error with allocating or freeing a debug register.
1943 There was an attempt to read from or write to an invalid area in
1944 the tracer's or the tracee's memory,
1945 probably because the area wasn't mapped or accessible.
1946 Unfortunately, under Linux, different variations of this fault
1951 more or less arbitrarily.
1954 An attempt was made to set an invalid option.
1958 is invalid, or an attempt was made to read from or
1959 write to an invalid area in the tracer's or the tracee's memory,
1960 or there was a word-alignment violation,
1961 or an invalid signal was specified during a restart request.
1964 The specified process cannot be traced.
1965 This could be because the
1966 tracer has insufficient privileges (the required capability is
1967 .BR CAP_SYS_PTRACE );
1968 unprivileged processes cannot trace processes that they
1969 cannot send signals to or those running
1970 set-user-ID/set-group-ID programs, for obvious reasons.
1971 Alternatively, the process may already be being traced,
1972 or (on kernels before 2.6.26) be
1977 The specified process does not exist, or is not currently being traced
1978 by the caller, or is not stopped
1979 (for requests that require a stopped tracee).
1983 Although arguments to
1985 are interpreted according to the prototype given,
1986 glibc currently declares
1988 as a variadic function with only the
1991 It is recommended to always supply four arguments,
1992 even if the requested operation does not use them,
1993 setting unused/ignored arguments to
1998 In Linux kernels before 2.6.26,
1999 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
2001 the process with PID 1, may not be traced.
2003 A tracees parent continues to be the tracer even if that tracer calls
2006 The layout of the contents of memory and the USER area are
2007 quite operating-system- and architecture-specific.
2008 The offset supplied, and the data returned,
2009 might not entirely match with the definition of
2011 .\" See http://lkml.org/lkml/2008/5/8/375
2013 The size of a "word" is determined by the operating-system variant
2014 (e.g., for 32-bit Linux it is 32 bits).
2016 This page documents the way the
2018 call works currently in Linux.
2019 Its behavior differs significantly on other flavors of UNIX.
2022 is highly specific to the operating system and architecture.
2023 .SS C library/kernel differences
2024 At the system call level, the
2025 .BR PTRACE_PEEKTEXT ,
2026 .BR PTRACE_PEEKDATA ,
2029 requests have a different API: they store the result
2030 at the address specified by the
2032 parameter, and the return value is the error flag.
2033 The glibc wrapper function provides the API given in DESCRIPTION above,
2034 with the result being returned via the function return value.
2036 On hosts with 2.6 kernel headers,
2037 .B PTRACE_SETOPTIONS
2038 is declared with a different value than the one for 2.4.
2039 This leads to applications compiled with 2.6 kernel
2040 headers failing when run on 2.4 kernels.
2041 This can be worked around by redefining
2042 .B PTRACE_SETOPTIONS
2044 .BR PTRACE_OLDSETOPTIONS ,
2047 Group-stop notifications are sent to the tracer, but not to real parent.
2048 Last confirmed on 2.6.38.6.
2050 If a thread group leader is traced and exits by calling
2052 .\" Note from Denys Vlasenko:
2053 .\" Here "exits" means any kind of death - _exit, exit_group,
2054 .\" signal death. Signal death and exit_group cases are trivial,
2055 .\" though: since signal death and exit_group kill all other threads
2056 .\" too, "until all other threads exit" thing happens rather soon
2057 .\" in these cases. Therefore, only _exit presents observably
2058 .\" puzzling behavior to ptrace users: thread leader _exit's,
2059 .\" but WIFEXITED isn't reported! We are trying to explain here
2062 .B PTRACE_EVENT_EXIT
2063 stop will happen for it (if requested), but the subsequent
2065 notification will not be delivered until all other threads exit.
2066 As explained above, if one of other threads calls
2068 the death of the thread group leader will
2071 If the execed thread is not traced by this tracer,
2072 the tracer will never know that
2075 One possible workaround is to
2077 the thread group leader instead of restarting it in this case.
2078 Last confirmed on 2.6.38.6.
2079 .\" FIXME . need to test/verify this scenario
2083 signal may still cause a
2084 .B PTRACE_EVENT_EXIT
2085 stop before actual signal death.
2086 This may be changed in the future;
2088 is meant to always immediately kill tasks even under ptrace.
2089 Last confirmed on Linux 3.13.
2091 Some system calls return with
2093 if a signal was sent to a tracee, but delivery was suppressed by the tracer.
2094 (This is very typical operation: it is usually
2095 done by debuggers on every attach, in order to not introduce
2098 As of Linux 3.2.9, the following system calls are affected
2099 (this list is likely incomplete):
2106 The usual symptom of this bug is that when you attach to
2107 a quiescent process with the command
2109 strace \-p <process-ID>
2111 then, instead of the usual
2112 and expected one-line output such as
2115 restart_syscall(<... resuming interrupted call ...>_
2121 select(6, [5], NULL, [5], NULL_
2124 ('_' denotes the cursor position), you observe more than one line.
2128 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
2132 What is not visible here is that the process was blocked in
2139 to return to user space with the error
2141 In this particular case, the program reacted to
2143 by checking the current time, and then executing
2146 (Programs which do not expect such "stray"
2148 errors may behave in an unintended way upon an
2164 .BR capabilities (7),