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 2013-07-11 "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
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.
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
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_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
321 Set ptrace options from
326 is interpreted as a bit mask of options,
327 which are specified by the following flags:
330 .BR PTRACE_O_EXITKILL " (since Linux 3.8)"
331 .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123
332 If a tracer sets this flag, a
334 signal will be sent to every tracee if the tracer exits.
335 This option is useful for ptrace jailers that
336 want to ensure that tracees can never escape the tracer's control.
338 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
339 Stop the tracee at the next
341 and automatically start tracing the newly cloned process,
342 which will start with a
351 by the tracer will return a
356 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
359 The PID of the new process can be retrieved with
360 .BR PTRACE_GETEVENTMSG .
362 This option may not catch
370 .B PTRACE_EVENT_VFORK
371 will be delivered instead
373 .B PTRACE_O_TRACEVFORK
374 is set; otherwise if the tracee calls
376 with the exit signal set to
380 .B PTRACE_O_TRACEFORK
383 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
384 Stop the tracee at the next
388 by the tracer will return a
393 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
396 If the execing thread is not a thread group leader,
397 the thread ID is reset to thread group leader's ID before this stop.
398 Since Linux 3.0, the former thread ID can be retrieved with
399 .BR PTRACE_GETEVENTMSG .
401 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
402 Stop the tracee at exit.
405 by the tracer will return a
410 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
413 The tracee's exit status can be retrieved with
414 .BR PTRACE_GETEVENTMSG .
416 The tracee is stopped early during process exit,
417 when registers are still available,
418 allowing the tracer to see where the exit occurred,
419 whereas the normal exit notification is done after the process
421 Even though context is available,
422 the tracer cannot prevent the exit from happening at this point.
424 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
425 Stop the tracee at the next
427 and automatically start tracing the newly forked process,
428 which will start with a
437 by the tracer will return a
442 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
445 The PID of the new process can be retrieved with
446 .BR PTRACE_GETEVENTMSG .
448 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
449 When delivering system call traps, set bit 7 in the signal number
451 .IR "SIGTRAP|0x80" ).
452 This makes it easy for the tracer to distinguish
453 normal traps from those caused by a system call.
454 .RB ( PTRACE_O_TRACESYSGOOD
455 may not work on all architectures.)
457 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
458 Stop the tracee at the next
460 and automatically start tracing the newly vforked process,
461 which will start with a
470 by the tracer will return a
475 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
478 The PID of the new process can be retrieved with
479 .BR PTRACE_GETEVENTMSG .
481 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
482 Stop the tracee at the completion of the next
486 by the tracer will return a
491 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
494 The PID of the new process can (since Linux 2.6.18) be retrieved with
495 .BR PTRACE_GETEVENTMSG .
498 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
499 Retrieve a message (as an
500 .IR "unsigned long" )
501 about the ptrace event
502 that just happened, placing it at the address
506 .BR PTRACE_EVENT_EXIT ,
507 this is the tracee's exit status.
509 .BR PTRACE_EVENT_FORK ,
510 .BR PTRACE_EVENT_VFORK ,
511 .BR PTRACE_EVENT_VFORK_DONE ,
513 .BR PTRACE_EVENT_CLONE ,
514 this is the PID of the new process.
519 Restart the stopped tracee process.
523 it is interpreted as the number of a signal to be delivered to the tracee;
524 otherwise, no signal is delivered.
525 Thus, for example, the tracer can control
526 whether a signal sent to the tracee is delivered or not.
530 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
531 Restart the stopped tracee as for
533 but arrange for the tracee to be stopped at
534 the next entry to or exit from a system call,
535 or after execution of a single instruction, respectively.
536 (The tracee will also, as usual, be stopped upon receipt of a signal.)
537 From the tracer's perspective, the tracee will appear to have been
538 stopped by receipt of a
542 for example, the idea is to inspect
543 the arguments to the system call at the first stop,
546 and inspect the return value of the system call at the second stop.
549 argument is treated as for
554 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
557 continue and stop on entry to the next system call,
558 which will not be executed.
560 .BR PTRACE_SYSEMU_SINGLESTEP ,
561 do the same but also singlestep if not a system call.
562 This call is used by programs like
563 User Mode Linux that want to emulate all the tracee's system calls.
566 argument is treated as for
571 These requests are currently
573 supported only on x86.
575 .BR PTRACE_LISTEN " (since Linux 3.4)"
576 Restart the stopped tracee, but prevent it from executing.
577 The resulting state of the tracee is similar to a process which
578 has been stopped by a
580 (or other stopping signal).
581 See the "group-stop" subsection for additional information.
583 works only on tracees attached by
595 .I This operation is deprecated; do not use it!
604 is that it requires the tracee to be in signal-delivery-stop,
605 otherwise it may not work
606 (i.e., may complete successfully but won't kill the tracee).
607 By contrast, sending a
609 directly has no such limitation.
610 .\" [Note from Denys Vlasenko:
611 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
612 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
614 .BR PTRACE_INTERRUPT " (since Linux 3.4)"
616 If the tracee is running or sleeping in kernel space and
619 the system call is interrupted and syscall-exit-stop is reported.
620 (The interrupted system call is restarted when the tracee is restarted.)
621 If the tracee was already stopped by a signal and
624 the tracee stops with
628 returns the stop signal.
629 If any other ptrace-stop is generated at the same time (for example,
630 if a signal is sent to the tracee), this ptrace-stop happens.
631 If none of the above applies (for example, if the tracee is running in userspace),
639 only works on tracees attached by
643 Attach to the process specified in
645 making it a tracee of the calling process.
646 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
647 .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
648 .\" Basically, it's not true for any Linux in practical use.
649 .\" ; the behavior of the tracee is as if it had done a
650 .\" .BR PTRACE_TRACEME .
651 .\" The calling process actually becomes the parent of the tracee
652 .\" process for most purposes (e.g., it will receive
653 .\" notification of tracee events and appears in
655 .\" output as the tracee's parent), but a
657 .\" by the tracee will still return the PID of the original parent.
660 but will not necessarily have stopped
661 by the completion of this call; use
663 to wait for the tracee to stop.
664 See the "Attaching and detaching" subsection for additional information.
670 .BR PTRACE_SEIZE " (since Linux 3.4)"
671 Attach to the process specified in
673 making it a tracee of the calling process.
677 does not stop the process.
688 contains a bit mask of ptrace options to activate immediately.
691 Restart the stopped tracee as for
693 but first detach from it.
694 Under Linux, a tracee can be detached in this way regardless
695 of which method was used to initiate tracing.
698 .SS Death under ptrace
699 When a (possibly multithreaded) process receives a killing signal
700 (one whose disposition is set to
702 and whose default action is to kill the process),
704 Tracees report their death to their tracer(s).
705 Notification of this event is delivered via
708 Note that the killing signal will first cause signal-delivery-stop
709 (on one tracee only),
710 and only after it is injected by the tracer
711 (or after it was dispatched to a thread which isn't traced),
712 will death from the signal happen on
714 tracees within a multithreaded process.
715 (The term "signal-delivery-stop" is explained below.)
718 does not generate signal-delivery-stop and
719 therefore the tracer can't suppress it.
721 kills even within system calls
722 (syscall-exit-stop is not generated prior to death by
724 The net effect is that
726 always kills the process (all its threads),
727 even if some threads of the process are ptraced.
729 When the tracee calls
731 it reports its death to its tracer.
732 Other threads are not affected.
734 When any thread executes
736 every tracee in its thread group reports its death to its tracer.
739 .B PTRACE_O_TRACEEXIT
742 will happen before actual death.
743 This applies to exits via
746 and signal deaths (except
748 and when threads are torn down on
750 in a multithreaded process.
752 The tracer cannot assume that the ptrace-stopped tracee exists.
753 There are many scenarios when the tracee may die while stopped (such as
755 Therefore, the tracer must be prepared to handle an
757 error on any ptrace operation.
758 Unfortunately, the same error is returned if the tracee
759 exists but is not ptrace-stopped
760 (for commands which require a stopped tracee),
761 or if it is not traced by the process which issued the ptrace call.
762 The tracer needs to keep track of the stopped/running state of the tracee,
765 as "tracee died unexpectedly" only if it knows that the tracee has
766 been observed to enter ptrace-stop.
767 Note that there is no guarantee that
769 will reliably report the tracee's death status if a
770 ptrace operation returned
773 may return 0 instead.
774 In other words, the tracee may be "not yet fully dead",
775 but already refusing ptrace requests.
777 The tracer can't assume that the tracee
779 ends its life by reporting
782 .IR WIFSIGNALED(status) ;
783 there are cases where this does not occur.
784 For example, if a thread other than thread group leader does an
787 its PID will never be seen again,
788 and any subsequent ptrace stops will be reported under
789 the thread group leader's PID.
791 A tracee can be in two states: running or stopped.
792 For the purposes of ptrace, a tracee which is blocked in a system call
797 is nevertheless considered to be running, even if the tracee is blocked
799 The state of the tracee after
801 is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
802 won't work on it, and it will deliver
805 but it also may be considered "stopped" because
806 it is not executing instructions (is not scheduled), and if it was
809 it will not respond to signals until
813 There are many kinds of states when the tracee is stopped, and in ptrace
814 discussions they are often conflated.
815 Therefore, it is important to use precise terms.
817 In this manual page, any stopped state in which the tracee is ready
818 to accept ptrace commands from the tracer is called
821 be further subdivided into
822 .IR signal-delivery-stop ,
826 These stopped states are described in detail below.
828 When the running tracee enters ptrace-stop, it notifies its tracer using
830 (or one of the other "wait" system calls).
831 Most of this manual page assumes that the tracer waits with:
833 pid = waitpid(pid_or_minus_1, &status, __WALL);
835 Ptrace-stopped tracees are reported as returns with
838 .I WIFSTOPPED(status)
841 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
842 .\" I am not 100% sure there aren't ugly corner cases.) Are the
843 .\" rules different if user wants to use waitid? Will waitid require
849 flag does not include the
853 flags, but implies their functionality.
859 is not recommended: the "continued" state is per-process and
860 consuming it can confuse the real parent of the tracee.
866 to return 0 ("no wait results available yet")
867 even if the tracer knows there should be a notification.
872 ptrace(PTRACE_CONT, pid, 0L, 0L);
873 if (errno == ESRCH) {
875 r = waitpid(tracee, &status, __WALL | WNOHANG);
876 /* r can still be 0 here! */
880 .\" waitid usage? WNOWAIT?
881 .\" describe how wait notifications queue (or not queue)
883 The following kinds of ptrace-stops exist: signal-delivery-stops,
886 stops, syscall-stops.
887 They all are reported by
890 .I WIFSTOPPED(status)
892 They may be differentiated by examining the value
894 and if there is ambiguity in that value, by querying
895 .BR PTRACE_GETSIGINFO .
898 macro can't be used to perform this examination,
899 because it returns the value
900 .IR "(status>>8)\ &\ 0xff" .)
901 .SS Signal-delivery-stop
902 When a (possibly multithreaded) process receives any signal except
904 the kernel selects an arbitrary thread which handles the signal.
905 (If the signal is generated with
907 the target thread can be explicitly selected by the caller.)
908 If the selected thread is traced, it enters signal-delivery-stop.
909 At this point, the signal is not yet delivered to the process,
910 and can be suppressed by the tracer.
911 If the tracer doesn't suppress the signal,
912 it passes the signal to the tracee in the next ptrace restart request.
913 This second step of signal delivery is called
914 .I "signal injection"
916 Note that if the signal is blocked,
917 signal-delivery-stop doesn't happen until the signal is unblocked,
918 with the usual exception that
922 Signal-delivery-stop is observed by the tracer as
925 .I WIFSTOPPED(status)
926 true, with the signal returned by
927 .IR WSTOPSIG(status) .
930 this may be a different kind of ptrace-stop;
931 see the "Syscall-stops" and "execve" sections below for details.
934 returns a stopping signal, this may be a group-stop; see below.
935 .SS Signal injection and suppression
936 After signal-delivery-stop is observed by the tracer,
937 the tracer should restart the tracee with the call
939 ptrace(PTRACE_restart, pid, 0, sig)
943 is one of the restarting ptrace requests.
946 is 0, then a signal is not delivered.
947 Otherwise, the signal
950 This operation is called
951 .I "signal injection"
952 in this manual page, to distinguish it from signal-delivery-stop.
956 value may be different from the
958 value: the tracer can cause a different signal to be injected.
960 Note that a suppressed signal still causes system calls to return
962 In this case system calls will be restarted: the tracer will
963 observe the tracee to reexecute the interrupted system call (or
964 .BR restart_syscall (2)
965 system call for a few syscalls which use a different mechanism
966 for restarting) if the tracer uses
968 Even system calls (such as
970 which are not restartable after signal are restarted after
971 signal is suppressed;
972 however, kernel bugs exist which cause some syscalls to fail with
974 even though no observable signal is injected to the tracee.
976 Restarting ptrace commands issued in ptrace-stops other than
977 signal-delivery-stop are not guaranteed to inject a signal, even if
980 No error is reported; a nonzero
982 may simply be ignored.
983 Ptrace users should not try to "create a new signal" this way: use
987 The fact that signal injection requests may be ignored
988 when restarting the tracee after
989 ptrace stops that are not signal-delivery-stops
990 is a cause of confusion among ptrace users.
991 One typical scenario is that the tracer observes group-stop,
992 mistakes it for signal-delivery-stop, restarts the tracee with
994 ptrace(PTRACE_restart, pid, 0, stopsig)
996 with the intention of injecting
1000 gets ignored and the tracee continues to run.
1004 signal has a side effect of waking up (all threads of)
1005 a group-stopped process.
1006 This side effect happens before signal-delivery-stop.
1007 The tracer can't suppress this side effect (it can
1008 only suppress signal injection, which only causes the
1010 handler to not be executed in the tracee, if such a handler is installed).
1011 In fact, waking up from group-stop may be followed by
1012 signal-delivery-stop for signal(s)
1015 if they were pending when
1020 may be not the first signal observed by the tracee after it was sent.
1022 Stopping signals cause (all threads of) a process to enter group-stop.
1023 This side effect happens after signal injection, and therefore can be
1024 suppressed by the tracer.
1026 In Linux 2.4 and earlier, the
1028 signal can't be injected.
1029 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
1032 .\" /* The debugger continued. Ignore SIGSTOP. */
1033 .\" if (signr == SIGSTOP)
1036 .B PTRACE_GETSIGINFO
1037 can be used to retrieve a
1039 structure which corresponds to the delivered signal.
1040 .B PTRACE_SETSIGINFO
1041 may be used to modify it.
1043 .B PTRACE_SETSIGINFO
1044 has been used to alter
1050 parameter in the restarting command must match,
1051 otherwise the result is undefined.
1053 When a (possibly multithreaded) process receives a stopping signal,
1055 If some threads are traced, they enter a group-stop.
1056 Note that the stopping signal will first cause signal-delivery-stop
1057 (on one tracee only), and only after it is injected by the tracer
1058 (or after it was dispatched to a thread which isn't traced),
1059 will group-stop be initiated on
1061 tracees within the multithreaded process.
1062 As usual, every tracee reports its group-stop separately
1063 to the corresponding tracer.
1065 Group-stop is observed by the tracer as
1068 .I WIFSTOPPED(status)
1069 true, with the stopping signal available via
1070 .IR WSTOPSIG(status) .
1071 The same result is returned by some other classes of ptrace-stops,
1072 therefore the recommended practice is to perform the call
1074 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
1076 The call can be avoided if the signal is not
1082 only these four signals are stopping signals.
1083 If the tracer sees something else, it can't be a group-stop.
1084 Otherwise, the tracer needs to call
1085 .BR PTRACE_GETSIGINFO .
1087 .B PTRACE_GETSIGINFO
1090 then it is definitely a group-stop.
1091 (Other failure codes are possible, such as
1093 ("no such process") if a
1097 If tracee was attached using
1099 group-stop is indicated by
1100 .BR PTRACE_EVENT_STOP :
1101 .IR "status>>16 == PTRACE_EVENT_STOP" .
1102 This allows detection of group-stops
1103 without requiring an extra
1104 .B PTRACE_GETSIGINFO
1108 after the tracer sees the tracee ptrace-stop and until it
1109 restarts or kills it, the tracee will not run,
1110 and will not send notifications (except
1112 death) to the tracer, even if the tracer enters into another
1116 The kernel behavior described in the previous paragraph
1117 causes a problem with transparent handling of stopping signals.
1118 If the tracer restarts the tracee after group-stop,
1120 is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
1121 If the tracer doesn't restart the tracee before entering into the next
1125 signals will not be reported to the tracer;
1126 this would cause the
1128 signals to have no effect on the tracee.
1130 Since Linux 3.4, there is a method to overcome this problem: instead of
1134 command can be used to restart a tracee in a way where it does not execute,
1135 but waits for a new event which it can report via
1138 it is restarted by a
1140 .SS PTRACE_EVENT stops
1143 options, the tracee will enter ptrace-stops called
1148 stops are observed by the tracer as
1151 .IR WIFSTOPPED(status) ,
1156 An additional bit is set in the higher byte of the status word:
1161 (SIGTRAP | PTRACE_EVENT_foo << 8).
1163 The following events exist:
1165 .B PTRACE_EVENT_VFORK
1166 Stop before return from
1173 When the tracee is continued after this stop, it will wait for child to
1174 exit/exec before continuing its execution
1175 (in other words, the usual behavior on
1178 .B PTRACE_EVENT_FORK
1179 Stop before return from
1183 with the exit signal set to
1186 .B PTRACE_EVENT_CLONE
1187 Stop before return from
1190 .B PTRACE_EVENT_VFORK_DONE
1191 Stop before return from
1198 but after the child unblocked this tracee by exiting or execing.
1200 For all four stops described above,
1201 the stop occurs in the parent (i.e., the tracee),
1202 not in the newly created thread.
1203 .BR PTRACE_GETEVENTMSG
1204 can be used to retrieve the new thread's ID.
1206 .B PTRACE_EVENT_EXEC
1207 Stop before return from
1210 .BR PTRACE_GETEVENTMSG
1211 returns the former thread ID.
1213 .B PTRACE_EVENT_EXIT
1214 Stop before exit (including death from
1215 .BR exit_group (2)),
1216 signal death, or exit caused by
1218 in a multithreaded process.
1219 .B PTRACE_GETEVENTMSG
1220 returns the exit status.
1221 Registers can be examined
1222 (unlike when "real" exit happens).
1223 The tracee is still alive; it needs to be
1226 .BR PTRACE_DETACH ed
1229 .B PTRACE_EVENT_STOP
1232 command, or group-stop, or initial ptrace-stop when a new child is attached
1233 (only if attached using
1236 .B PTRACE_EVENT_STOP
1241 .B PTRACE_GETSIGINFO
1251 .IR "(event<<8)\ |\ SIGTRAP" .
1253 If the tracee was restarted by
1254 .BR PTRACE_SYSCALL ,
1256 syscall-enter-stop just prior to entering any system call.
1257 If the tracer restarts the tracee with
1258 .BR PTRACE_SYSCALL ,
1259 the tracee enters syscall-exit-stop when the system call is finished,
1260 or if it is interrupted by a signal.
1261 (That is, signal-delivery-stop never happens between syscall-enter-stop
1262 and syscall-exit-stop; it happens
1266 Other possibilities are that the tracee may stop in a
1268 stop, exit (if it entered
1271 .BR exit_group (2)),
1274 or die silently (if it is a thread group leader, the
1276 happened in another thread,
1277 and that thread is not traced by the same tracer;
1278 this situation is discussed later).
1280 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1283 .I WIFSTOPPED(status)
1289 .B PTRACE_O_TRACESYSGOOD
1290 option was set by the tracer, then
1293 .IR "(SIGTRAP\ |\ 0x80)" .
1295 Syscall-stops can be distinguished from signal-delivery-stop with
1298 .BR PTRACE_GETSIGINFO
1299 for the following cases:
1303 was delivered as a result of a user-space action,
1304 for example, a system call
1309 expiration of a POSIX timer,
1310 change of state on a POSIX message queue,
1311 or completion of an asynchronous I/O request.
1313 .IR si_code " == SI_KERNEL (0x80)"
1315 was sent by the kernel.
1317 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1318 This is a syscall-stop.
1320 However, syscall-stops happen very often (twice per system call),
1322 .B PTRACE_GETSIGINFO
1323 for every syscall-stop may be somewhat expensive.
1325 Some architectures allow the cases to be distinguished
1326 by examining registers.
1327 For example, on x86,
1331 in syscall-enter-stop.
1334 (like any other signal) always happens
1339 almost never contains
1343 looks like "syscall-stop which is not syscall-enter-stop";
1344 in other words, it looks like a
1345 "stray syscall-exit-stop" and can be detected this way.
1346 But such detection is fragile and is best avoided.
1349 .B PTRACE_O_TRACESYSGOOD
1350 option is the recommended method to distinguish syscall-stops
1351 from other kinds of ptrace-stops,
1352 since it is reliable and does not incur a performance penalty.
1354 Syscall-enter-stop and syscall-exit-stop are
1355 indistinguishable from each other by the tracer.
1356 The tracer needs to keep track of the sequence of
1357 ptrace-stops in order to not misinterpret syscall-enter-stop as
1358 syscall-exit-stop or vice versa.
1359 The rule is that syscall-enter-stop is
1360 always followed by syscall-exit-stop,
1362 stop or the tracee's death;
1363 no other kinds of ptrace-stop can occur in between.
1365 If after syscall-enter-stop,
1366 the tracer uses a restarting command other than
1367 .BR PTRACE_SYSCALL ,
1368 syscall-exit-stop is not generated.
1370 .B PTRACE_GETSIGINFO
1371 on syscall-stops returns
1380 .IR (SIGTRAP|0x80) .
1381 .SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops
1382 [Details of these kinds of stops are yet to be documented.]
1385 .\" document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
1386 .\" PTRACE_SYSEMU_SINGLESTEP
1387 .SS Informational and restarting ptrace commands
1388 Most ptrace commands (all except
1391 .BR PTRACE_TRACEME ,
1392 .BR PTRACE_INTERRUPT ,
1395 require the tracee to be in a ptrace-stop, otherwise they fail with
1398 When the tracee is in ptrace-stop,
1399 the tracer can read and write data to
1400 the tracee using informational commands.
1401 These commands leave the tracee in ptrace-stopped state:
1404 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1405 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1406 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1407 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1408 ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
1409 ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
1410 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1411 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1412 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
1413 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1416 Note that some errors are not reported.
1417 For example, setting signal information
1419 may have no effect in some ptrace-stops, yet the call may succeed
1420 (return 0 and not set
1423 .B PTRACE_GETEVENTMSG
1424 may succeed and return some random value if current ptrace-stop
1425 is not documented as returning a meaningful event message.
1429 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1432 The tracee's current flags are replaced.
1433 Flags are inherited by new tracees created and "auto-attached" via active
1434 .BR PTRACE_O_TRACEFORK ,
1435 .BR PTRACE_O_TRACEVFORK ,
1437 .BR PTRACE_O_TRACECLONE
1440 Another group of commands makes the ptrace-stopped tracee run.
1443 ptrace(cmd, pid, 0, sig);
1451 .BR PTRACE_SYSCALL ,
1452 .BR PTRACE_SINGLESTEP ,
1455 .BR PTRACE_SYSEMU_SINGLESTEP .
1456 If the tracee is in signal-delivery-stop,
1458 is the signal to be injected (if it is nonzero).
1462 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
1463 recommended practice is to always pass 0 in
1465 .SS Attaching and detaching
1466 A thread can be attached to the tracer using the call
1468 ptrace(PTRACE_ATTACH, pid, 0, 0);
1472 ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
1478 If the tracer wants this
1480 to have no effect, it needs to suppress it.
1481 Note that if other signals are concurrently sent to
1482 this thread during attach,
1483 the tracer may see the tracee enter signal-delivery-stop
1484 with other signal(s) first!
1485 The usual practice is to reinject these signals until
1487 is seen, then suppress
1490 The design bug here is that a ptrace attach and a concurrently delivered
1492 may race and the concurrent
1496 .\" FIXME: Describe how to attach to a thread which is already
1499 Since attaching sends
1501 and the tracer usually suppresses it, this may cause a stray
1503 return from the currently executing system call in the tracee,
1504 as described in the "Signal injection and suppression" section.
1508 can be used instead of
1511 does not stop the attached process.
1513 it after attach (or at any other time) without sending it any signals,
1520 ptrace(PTRACE_TRACEME, 0, 0, 0);
1522 turns the calling thread into a tracee.
1523 The thread continues to run (doesn't enter ptrace-stop).
1524 A common practice is to follow the
1530 and allow the parent (which is our tracer now) to observe our
1531 signal-delivery-stop.
1534 .BR PTRACE_O_TRACEFORK ,
1535 .BR PTRACE_O_TRACEVFORK ,
1537 .BR PTRACE_O_TRACECLONE
1538 options are in effect, then children created by, respectively,
1548 with the exit signal set to
1552 are automatically attached to the same tracer which traced their parent.
1554 is delivered to the children, causing them to enter
1555 signal-delivery-stop after they exit the system call which created them.
1557 Detaching of the tracee is performed by:
1559 ptrace(PTRACE_DETACH, pid, 0, sig);
1562 is a restarting operation;
1563 therefore it requires the tracee to be in ptrace-stop.
1564 If the tracee is in signal-delivery-stop, a signal can be injected.
1567 parameter may be silently ignored.
1569 If the tracee is running when the tracer wants to detach it,
1570 the usual solution is to send
1574 to make sure it goes to the correct thread),
1575 wait for the tracee to stop in signal-delivery-stop for
1577 and then detach it (suppressing
1580 A design bug is that this can race with concurrent
1582 Another complication is that the tracee may enter other ptrace-stops
1583 and needs to be restarted and waited for again, until
1586 Yet another complication is to be sure that
1587 the tracee is not already ptrace-stopped,
1588 because no signal delivery happens while it is\(emnot even
1590 .\" FIXME: Describe how to detach from a group-stopped tracee so that it
1591 .\" doesn't run, but continues to wait for SIGCONT.
1593 If the tracer dies, all tracees are automatically detached and restarted,
1594 unless they were in group-stop.
1595 Handling of restart from group-stop is currently buggy,
1596 but the "as planned" behavior is to leave tracee stopped and waiting for
1598 If the tracee is restarted from signal-delivery-stop,
1599 the pending signal is injected.
1600 .SS execve(2) under ptrace
1601 .\" clone(2) CLONE_THREAD says:
1602 .\" If any of the threads in a thread group performs an execve(2),
1603 .\" then all threads other than the thread group leader are terminated,
1604 .\" and the new program is executed in the thread group leader.
1606 When one thread in a multithreaded process calls
1608 the kernel destroys all other threads in the process,
1609 .\" In kernel 3.1 sources, see fs/exec.c::de_thread()
1610 and resets the thread ID of the execing thread to the
1611 thread group ID (process ID).
1612 (Or, to put things another way, when a multithreaded process does an
1614 at completion of the call, it appears as though the
1616 occurred in the thread group leader, regardless of which thread did the
1618 This resetting of the thread ID looks very confusing to tracers:
1620 All other threads stop in
1621 .B PTRACE_EVENT_EXIT
1623 .BR PTRACE_O_TRACEEXIT
1624 option was turned on.
1625 Then all other threads except the thread group leader report
1626 death as if they exited via
1630 The execing tracee changes its thread ID while it is in the
1632 (Remember, under ptrace, the "pid" returned from
1634 or fed into ptrace calls, is the tracee's thread ID.)
1635 That is, the tracee's thread ID is reset to be the same as its process ID,
1636 which is the same as the thread group leader's thread ID.
1639 .B PTRACE_EVENT_EXEC
1640 stop happens, if the
1641 .BR PTRACE_O_TRACEEXEC
1642 option was turned on.
1644 If the thread group leader has reported its
1645 .B PTRACE_EVENT_EXIT
1647 it appears to the tracer that
1648 the dead thread leader "reappears from nowhere".
1649 (Note: the thread group leader does not report death via
1650 .I WIFEXITED(status)
1651 until there is at least one other live thread.
1652 This eliminates the possibility that the tracer will see
1653 it dying and then reappearing.)
1654 If the thread group leader was still alive,
1655 for the tracer this may look as if thread group leader
1656 returns from a different system call than it entered,
1657 or even "returned from a system call even though
1658 it was not in any system call".
1659 If the thread group leader was not traced
1660 (or was traced by a different tracer), then during
1662 it will appear as if it has become a tracee of
1663 the tracer of the execing tracee.
1665 All of the above effects are the artifacts of
1666 the thread ID change in the tracee.
1669 .B PTRACE_O_TRACEEXEC
1670 option is the recommended tool for dealing with this situation.
1672 .BR PTRACE_EVENT_EXEC
1677 In this stop, the tracer can use
1678 .B PTRACE_GETEVENTMSG
1679 to retrieve the tracee's former thread ID.
1680 (This feature was introduced in Linux 3.0).
1682 .B PTRACE_O_TRACEEXEC
1683 option disables legacy
1688 When the tracer receives
1689 .B PTRACE_EVENT_EXEC
1691 it is guaranteed that except this tracee and the thread group leader,
1692 no other threads from the process are alive.
1695 .B PTRACE_EVENT_EXEC
1697 the tracer should clean up all its internal
1698 data structures describing the threads of this process,
1699 and retain only one data structure\(emone which
1700 describes the single still running tracee, with
1702 thread ID == thread group ID == process ID.
1704 Example: two threads call
1709 *** we get syscall-enter-stop in thread 1: **
1710 PID1 execve("/bin/foo", "foo" <unfinished ...>
1711 *** we issue PTRACE_SYSCALL for thread 1 **
1712 *** we get syscall-enter-stop in thread 2: **
1713 PID2 execve("/bin/bar", "bar" <unfinished ...>
1714 *** we issue PTRACE_SYSCALL for thread 2 **
1715 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
1716 *** we get syscall-exit-stop for PID0: **
1717 PID0 <... execve resumed> ) = 0
1721 .B PTRACE_O_TRACEEXEC
1724 in effect for the execing tracee, the kernel delivers an extra
1729 This is an ordinary signal (similar to one which can be
1732 not a special kind of ptrace-stop.
1734 .B PTRACE_GETSIGINFO
1735 for this signal returns
1739 This signal may be blocked by signal mask,
1740 and thus may be delivered (much) later.
1742 Usually, the tracer (for example,
1744 would not want to show this extra post-execve
1746 signal to the user, and would suppress its delivery to the tracee (if
1750 it is a killing signal).
1751 However, determining
1754 to suppress is not easy.
1756 .B PTRACE_O_TRACEEXEC
1757 option and thus suppressing this extra
1759 is the recommended approach.
1761 The ptrace API (ab)uses the standard UNIX parent/child signaling over
1763 This used to cause the real parent of the process to stop receiving
1766 notifications when the child process is traced by some other process.
1768 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
1769 exist; see BUGS below.
1771 As of Linux 2.6.38, the following is believed to work correctly:
1773 exit/death by signal is reported first to the tracer, then,
1774 when the tracer consumes the
1776 result, to the real parent (to the real parent only when the
1777 whole multithreaded process exits).
1778 If the tracer and the real parent are the same process,
1779 the report is sent only once.
1783 requests return the requested data, while other requests return zero.
1784 (On Linux, this is done in the libc wrapper around ptrace system call.
1785 On the system call level,
1787 requests have a different API: they store the result
1788 at the address specified by
1790 parameter, and return value is the error flag.)
1792 On error, all requests return \-1, and
1794 is set appropriately.
1795 Since the value returned by a successful
1797 request may be \-1, the caller must clear
1799 before the call, and then check it afterward
1800 to determine whether or not an error occurred.
1804 (i386 only) There was an error with allocating or freeing a debug register.
1807 There was an attempt to read from or write to an invalid area in
1808 the tracer's or the tracee's memory,
1809 probably because the area wasn't mapped or accessible.
1810 Unfortunately, under Linux, different variations of this fault
1815 more or less arbitrarily.
1818 An attempt was made to set an invalid option.
1822 is invalid, or an attempt was made to read from or
1823 write to an invalid area in the tracer's or the tracee's memory,
1824 or there was a word-alignment violation,
1825 or an invalid signal was specified during a restart request.
1828 The specified process cannot be traced.
1829 This could be because the
1830 tracer has insufficient privileges (the required capability is
1831 .BR CAP_SYS_PTRACE );
1832 unprivileged processes cannot trace processes that they
1833 cannot send signals to or those running
1834 set-user-ID/set-group-ID programs, for obvious reasons.
1835 Alternatively, the process may already be being traced,
1836 or (on kernels before 2.6.26) be
1841 The specified process does not exist, or is not currently being traced
1842 by the caller, or is not stopped
1843 (for requests that require a stopped tracee).
1847 Although arguments to
1849 are interpreted according to the prototype given,
1850 glibc currently declares
1852 as a variadic function with only the
1855 It is recommended to always supply four arguments,
1856 even if the requested operation does not use them,
1857 setting unused/ignored arguments to
1862 In Linux kernels before 2.6.26,
1863 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
1865 the process with PID 1, may not be traced.
1867 The layout of the contents of memory and the USER area are
1868 quite operating-system- and architecture-specific.
1869 The offset supplied, and the data returned,
1870 might not entirely match with the definition of
1872 .\" See http://lkml.org/lkml/2008/5/8/375
1874 The size of a "word" is determined by the operating-system variant
1875 (e.g., for 32-bit Linux it is 32 bits).
1877 This page documents the way the
1879 call works currently in Linux.
1880 Its behavior differs noticeably on other flavors of UNIX.
1883 is highly specific to the operating system and architecture.
1885 On hosts with 2.6 kernel headers,
1886 .B PTRACE_SETOPTIONS
1887 is declared with a different value than the one for 2.4.
1888 This leads to applications compiled with 2.6 kernel
1889 headers failing when run on 2.4 kernels.
1890 This can be worked around by redefining
1891 .B PTRACE_SETOPTIONS
1893 .BR PTRACE_OLDSETOPTIONS ,
1896 Group-stop notifications are sent to the tracer, but not to real parent.
1897 Last confirmed on 2.6.38.6.
1899 If a thread group leader is traced and exits by calling
1901 .\" Note from Denys Vlasenko:
1902 .\" Here "exits" means any kind of death - _exit, exit_group,
1903 .\" signal death. Signal death and exit_group cases are trivial,
1904 .\" though: since signal death and exit_group kill all other threads
1905 .\" too, "until all other threads exit" thing happens rather soon
1906 .\" in these cases. Therefore, only _exit presents observably
1907 .\" puzzling behavior to ptrace users: thread leader _exit's,
1908 .\" but WIFEXITED isn't reported! We are trying to explain here
1911 .B PTRACE_EVENT_EXIT
1912 stop will happen for it (if requested), but the subsequent
1914 notification will not be delivered until all other threads exit.
1915 As explained above, if one of other threads calls
1917 the death of the thread group leader will
1920 If the execed thread is not traced by this tracer,
1921 the tracer will never know that
1924 One possible workaround is to
1926 the thread group leader instead of restarting it in this case.
1927 Last confirmed on 2.6.38.6.
1928 .\" FIXME: ^^^ need to test/verify this scenario
1932 signal may still cause a
1933 .B PTRACE_EVENT_EXIT
1934 stop before actual signal death.
1935 This may be changed in the future;
1937 is meant to always immediately kill tasks even under ptrace.
1938 Last confirmed on 2.6.38.6.
1940 Some system calls return with
1942 if a signal was sent to a tracee, but delivery was suppressed by the tracer.
1943 (This is very typical operation: it is usually
1944 done by debuggers on every attach, in order to not introduce
1947 As of Linux 3.2.9, the following system calls are affected
1948 (this list is likely incomplete):
1955 The usual symptom of this bug is that when you attach to
1956 a quiescent process with the command
1958 strace \-p <process-ID>
1960 then, instead of the usual
1961 and expected one-line output such as
1964 restart_syscall(<... resuming interrupted call ...>_
1970 select(6, [5], NULL, [5], NULL_
1973 ('_' denotes the cursor position), you observe more than one line.
1977 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
1981 What is not visible here is that the process was blocked in
1988 to return to user space with the error
1990 In this particular case, the program reacted to
1992 by checking the current time, and then executing
1995 (Programs which do not expect such "stray"
1997 errors may behave in an unintended way upon an
2012 .BR capabilities (7),