1 .\" Hey Emacs! This file is -*- nroff -*- source.
3 .\" Copyright (c) 1993 Michael Haardt <michael@moria.de>
4 .\" Fri Apr 2 11:32:09 MET DST 1993
6 .\" and changes Copyright (C) 1999 Mike Coleman (mkc@acm.org)
7 .\" -- major revision to fully document ptrace semantics per recent Linux
8 .\" kernel (2.2.10) and glibc (2.1.2)
9 .\" Sun Nov 7 03:18:35 CST 1999
11 .\" and Copyright (c) 2011, Denys Vlasenko <vda.linux@googlemail.com>
13 .\" This is free documentation; you can redistribute it and/or
14 .\" modify it under the terms of the GNU General Public License as
15 .\" published by the Free Software Foundation; either version 2 of
16 .\" the License, or (at your option) any later version.
18 .\" The GNU General Public License's references to "object code"
19 .\" and "executables" are to be interpreted as the output of any
20 .\" document formatting or typesetting system, including
21 .\" intermediate and printed output.
23 .\" This manual is distributed in the hope that it will be useful,
24 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
25 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
26 .\" GNU General Public License for more details.
28 .\" You should have received a copy of the GNU General Public
29 .\" License along with this manual; if not, write to the Free
30 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
33 .\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith <faith@cs.unc.edu>
34 .\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond <esr@thyrsus.com>
35 .\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer <aeb@cwi.nl>
36 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
37 .\" Added notes on capability requirements
39 .\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com>
40 .\" Added PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO,
41 .\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP
42 .\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.)
43 .\" 2011-09, major update by Denys Vlasenko <vda.linux@googlemail.com>
45 .TH PTRACE 2 2013-02-16 "Linux" "Linux Programmer's Manual"
47 ptrace \- process trace
50 .B #include <sys/ptrace.h>
52 .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
53 .BI " void *" addr ", void *" data );
58 system call provides a means by which one process (the "tracer")
59 may observe and control the execution of another process (the "tracee"),
60 and examine and change the tracee's memory and registers.
61 It is primarily used to implement breakpoint debugging and system
64 A tracee first needs to be attached to the tracer.
65 Attachment and subsequent commands are per thread:
66 in a multithreaded process,
67 every thread can be individually attached to a
68 (potentially different) tracer,
69 or left not attached and thus not debugged.
70 Therefore, "tracee" always means "(one) thread",
71 never "a (possibly multithreaded) process".
72 Ptrace commands are always sent to
73 a specific tracee using a call of the form
75 ptrace(PTRACE_foo, pid, ...)
79 is the thread ID of the corresponding Linux thread.
81 (Note that in this page, a "multithreaded process"
82 means a thread group consisting of threads created using the
87 A process can initiate a trace by calling
89 and having the resulting child do a
91 followed (typically) by an
93 Alternatively, one process may commence tracing another process using
98 While being traced, the tracee will stop each time a signal is delivered,
99 even if the signal is being ignored.
102 which has its usual effect.)
103 The tracer will be notified at its next call to
105 (or one of the related "wait" system calls); that call will return a
107 value containing information that indicates
108 the cause of the stop in the tracee.
109 While the tracee is stopped,
110 the tracer can use various ptrace requests to inspect and modify the tracee.
111 The tracer then causes the tracee to continue,
112 optionally ignoring the delivered signal
113 (or even delivering a different signal instead).
116 .B PTRACE_O_TRACEEXEC
117 option is not in effect, all successful calls to
119 by the traced process will cause it to be sent a
122 giving the parent a chance to gain control before the new program
125 When the tracer is finished tracing, it can cause the tracee to continue
126 executing in a normal, untraced mode via
131 determines the action to be performed:
134 Indicate that this process is to be traced by its parent.
135 A process probably shouldn't make this request if its parent
136 isn't expecting to trace it.
145 request is used only by the tracee;
146 the remaining requests are used only by the tracer.
147 In the following requests,
149 specifies the thread ID of the tracee to be acted on.
150 For requests other than
156 the tracee must be stopped.
158 .BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA
159 Read a word at the address
161 in the tracee's memory, returning the word as the result of the
164 Linux does not have separate text and data address spaces,
165 so these two requests are currently equivalent.
170 .\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
171 .\" and that is the name that seems common on other systems.
172 Read a word at offset
174 in the tracee's USER area,
175 which holds the registers and other information about the process
178 The word is returned as the result of the
181 Typically, the offset must be word-aligned, though this might vary by
187 .BR PTRACE_POKETEXT ", " PTRACE_POKEDATA
192 in the tracee's memory.
196 .BR PTRACE_PEEKDATA ,
197 these two requests are currently equivalent.
200 .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
201 .\" and that is the name that seems common on other systems.
206 in the tracee's USER area.
208 .BR PTRACE_PEEKUSER ,
209 the offset must typically be word-aligned.
210 In order to maintain the integrity of the kernel,
211 some modifications to the USER area are disallowed.
212 .\" FIXME In the preceding sentence, which modifications are disallowed,
213 .\" and when they are disallowed, how does user space discover that fact?
215 .BR PTRACE_GETREGS ", " PTRACE_GETFPREGS
216 Read the tracee's general-purpose or floating-point registers,
217 respectively, to the address
222 for information on the format of this data.
225 Note that SPARC systems have the meaning of
231 is ignored and the registers are copied to the address
236 are not present on all architectures.
238 .BR PTRACE_GETREGSET " (since Linux 2.6.34)"
239 Read the tracee's registers.
241 specifies, in an architecture-dependent way, the type of registers to be read.
243 (with numerical value 1)
244 usually results in reading of general-purpose registers.
245 If the CPU has, for example,
246 floating-point and/or vector registers, they can be retrieved by setting
254 which describes ithe destination buffer's location and length.
255 On return, the kernel modifies
257 to indicate the actual number of bytes returned.
259 .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
260 Retrieve information about the signal that caused the stop.
265 from the tracee to the address
271 .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
272 Modify the tracee's general-purpose or floating-point registers,
273 respectively, from the address
277 .BR PTRACE_POKEUSER ,
278 some general-purpose register modifications may be disallowed.
279 .\" FIXME In the preceding sentence, which modifications are disallowed,
280 .\" and when they are disallowed, how does user space discover that fact?
283 Note that SPARC systems have the meaning of
289 is ignored and the registers are copied from the address
294 are not present on all architectures.
296 .BR PTRACE_SETREGSET " (since Linux 2.6.34)"
297 Modify the tracee's registers.
303 .BR PTRACE_GETREGSET .
305 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
306 Set signal information:
309 structure from the address
311 in the tracer to the tracee.
312 This will affect only signals that would normally be delivered to
313 the tracee and were caught by the tracer.
314 It may be difficult to tell
315 these normal signals from synthetic signals generated by
321 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
322 Set ptrace options from
327 is interpreted as a bit mask of options,
328 which are specified by the following flags:
331 .BR PTRACE_O_EXITKILL " (since Linux 3.8)"
332 .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123
333 If a tracer sets this flag, a
335 signal will be sent to every tracee if the tracer exits.
336 This option is useful for ptrace jailers that
337 want to ensure that tracees can never escape the tracer's control.
339 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
340 Stop the tracee at the next
342 and automatically start tracing the newly cloned process,
343 which will start with a
347 by the tracer will return a
352 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
355 The PID of the new process can be retrieved with
356 .BR PTRACE_GETEVENTMSG .
358 This option may not catch
366 .B PTRACE_EVENT_VFORK
367 will be delivered instead
369 .B PTRACE_O_TRACEVFORK
370 is set; otherwise if the tracee calls
372 with the exit signal set to
376 .B PTRACE_O_TRACEFORK
379 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
380 Stop the tracee at the next
384 by the tracer will return a
389 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
392 If the execing thread is not a thread group leader,
393 the thread ID is reset to thread group leader's ID before this stop.
394 Since Linux 3.0, the former thread ID can be retrieved with
395 .BR PTRACE_GETEVENTMSG .
397 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
398 Stop the tracee at exit.
401 by the tracer will return a
406 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
409 The tracee's exit status can be retrieved with
410 .BR PTRACE_GETEVENTMSG .
412 The tracee is stopped early during process exit,
413 when registers are still available,
414 allowing the tracer to see where the exit occurred,
415 whereas the normal exit notification is done after the process
417 Even though context is available,
418 the tracer cannot prevent the exit from happening at this point.
420 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
421 Stop the tracee at the next
423 and automatically start tracing the newly forked process,
424 which will start with a
428 by the tracer will return a
433 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
436 The PID of the new process can be retrieved with
437 .BR PTRACE_GETEVENTMSG .
439 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
440 When delivering system call traps, set bit 7 in the signal number
442 .IR "SIGTRAP|0x80" ).
443 This makes it easy for the tracer to distinguish
444 normal traps from those caused by a system call.
445 .RB ( PTRACE_O_TRACESYSGOOD
446 may not work on all architectures.)
448 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
449 Stop the tracee at the next
451 and automatically start tracing the newly vforked process,
452 which will start with a
456 by the tracer will return a
461 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
464 The PID of the new process can be retrieved with
465 .BR PTRACE_GETEVENTMSG .
467 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
468 Stop the tracee at the completion of the next
472 by the tracer will return a
477 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
480 The PID of the new process can (since Linux 2.6.18) be retrieved with
481 .BR PTRACE_GETEVENTMSG .
484 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
485 Retrieve a message (as an
486 .IR "unsigned long" )
487 about the ptrace event
488 that just happened, placing it at the address
492 .BR PTRACE_EVENT_EXIT ,
493 this is the tracee's exit status.
495 .BR PTRACE_EVENT_FORK ,
496 .BR PTRACE_EVENT_VFORK ,
497 .BR PTRACE_EVENT_VFORK_DONE ,
499 .BR PTRACE_EVENT_CLONE ,
500 this is the PID of the new process.
505 Restart the stopped tracee process.
509 it is interpreted as the number of a signal to be delivered to the tracee;
510 otherwise, no signal is delivered.
511 Thus, for example, the tracer can control
512 whether a signal sent to the tracee is delivered or not.
516 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
517 Restart the stopped tracee as for
519 but arrange for the tracee to be stopped at
520 the next entry to or exit from a system call,
521 or after execution of a single instruction, respectively.
522 (The tracee will also, as usual, be stopped upon receipt of a signal.)
523 From the tracer's perspective, the tracee will appear to have been
524 stopped by receipt of a
528 for example, the idea is to inspect
529 the arguments to the system call at the first stop,
532 and inspect the return value of the system call at the second stop.
535 argument is treated as for
540 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
543 continue and stop on entry to the next system call,
544 which will not be executed.
546 .BR PTRACE_SYSEMU_SINGLESTEP ,
547 do the same but also singlestep if not a system call.
548 This call is used by programs like
549 User Mode Linux that want to emulate all the tracee's system calls.
552 argument is treated as for
557 These requests are currently
559 supported only on x86.
561 .BR PTRACE_LISTEN " (since Linux 3.4)"
562 Restart the stopped tracee, but prevent it from executing.
563 The resulting state of the tracee is similar to a process which
564 has been stopped by a
566 (or other stopping signal).
567 See the "group-stop" subsection for additional information.
569 only works on tracees attached by
581 .I This operation is deprecated; do not use it!
590 is that it requires the tracee to be in signal-delivery-stop,
591 otherwise it may not work
592 (i.e., may complete successfully but won't kill the tracee).
593 By contrast, sending a
595 directly has no such limitation.
596 .\" [Note from Denys Vlasenko:
597 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
598 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
600 .BR PTRACE_INTERRUPT " (since Linux 3.4)"
602 If the tracee is running, it will stop with
603 .BR PTRACE_EVENT_STOP .
604 If the tracee is already stopped by a signal, or receives a signal
606 .BR PTRACE_INTERRUPT ,
607 it may report a group-stop
608 or a signal-delivery-stop instead of
609 .BR PTRACE_EVENT_STOP .
611 only works on tracees attached by
615 Attach to the process specified in
617 making it a tracee of the calling process.
618 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
619 .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
620 .\" Basically, it's not true for any Linux in practical use.
621 .\" ; the behavior of the tracee is as if it had done a
622 .\" .BR PTRACE_TRACEME .
623 .\" The calling process actually becomes the parent of the tracee
624 .\" process for most purposes (e.g., it will receive
625 .\" notification of tracee events and appears in
627 .\" output as the tracee's parent), but a
629 .\" by the tracee will still return the PID of the original parent.
632 but will not necessarily have stopped
633 by the completion of this call; use
635 to wait for the tracee to stop.
636 See the "Attaching and detaching" subsection for additional information.
642 .BR PTRACE_SEIZE " (since Linux 3.4)"
643 Attach to the process specified in
645 making it a tracee of the calling process.
649 does not stop the process.
660 contains a bit mask of ptrace options to activate immediately.
663 Restart the stopped tracee as for
665 but first detach from it.
666 Under Linux, a tracee can be detached in this way regardless
667 of which method was used to initiate tracing.
670 .SS Death under ptrace
671 When a (possibly multithreaded) process receives a killing signal
672 (one whose disposition is set to
674 and whose default action is to kill the process),
676 Tracees report their death to their tracer(s).
677 Notification of this event is delivered via
680 Note that the killing signal will first cause signal-delivery-stop
681 (on one tracee only),
682 and only after it is injected by the tracer
683 (or after it was dispatched to a thread which isn't traced),
684 will death from the signal happen on
686 tracees within a multithreaded process.
687 (The term "signal-delivery-stop" is explained below.)
690 does not generate signal-delivery-stop and
691 therefore the tracer can't suppress it.
693 kills even within system calls
694 (syscall-exit-stop is not generated prior to death by
696 The net effect is that
698 always kills the process (all its threads),
699 even if some threads of the process are ptraced.
701 When the tracee calls
703 it reports its death to its tracer.
704 Other threads are not affected.
706 When any thread executes
708 every tracee in its thread group reports its death to its tracer.
711 .B PTRACE_O_TRACEEXIT
714 will happen before actual death.
715 This applies to exits via
718 and signal deaths (except
720 and when threads are torn down on
722 in a multithreaded process.
724 The tracer cannot assume that the ptrace-stopped tracee exists.
725 There are many scenarios when the tracee may die while stopped (such as
727 Therefore, the tracer must be prepared to handle an
729 error on any ptrace operation.
730 Unfortunately, the same error is returned if the tracee
731 exists but is not ptrace-stopped
732 (for commands which require a stopped tracee),
733 or if it is not traced by the process which issued the ptrace call.
734 The tracer needs to keep track of the stopped/running state of the tracee,
737 as "tracee died unexpectedly" only if it knows that the tracee has
738 been observed to enter ptrace-stop.
739 Note that there is no guarantee that
741 will reliably report the tracee's death status if a
742 ptrace operation returned
745 may return 0 instead.
746 In other words, the tracee may be "not yet fully dead",
747 but already refusing ptrace requests.
749 The tracer can't assume that the tracee
751 ends its life by reporting
754 .IR WIFSIGNALED(status) ;
755 there are cases where this does not occur.
756 For example, if a thread other than thread group leader does an
759 its PID will never be seen again,
760 and any subsequent ptrace stops will be reported under
761 the thread group leader's PID.
763 A tracee can be in two states: running or stopped.
765 There are many kinds of states when the tracee is stopped, and in ptrace
766 discussions they are often conflated.
767 Therefore, it is important to use precise terms.
769 In this manual page, any stopped state in which the tracee is ready
770 to accept ptrace commands from the tracer is called
773 be further subdivided into
774 .IR signal-delivery-stop ,
778 These stopped states are described in detail below.
780 When the running tracee enters ptrace-stop, it notifies its tracer using
782 (or one of the other "wait" system calls).
783 Most of this manual page assumes that the tracer waits with:
785 pid = waitpid(pid_or_minus_1, &status, __WALL);
787 Ptrace-stopped tracees are reported as returns with
790 .I WIFSTOPPED(status)
793 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
794 .\" I am not 100% sure there aren't ugly corner cases.) Are the
795 .\" rules different if user wants to use waitid? Will waitid require
801 flag does not include the
805 flags, but implies their functionality.
811 is not recommended: the "continued" state is per-process and
812 consuming it can confuse the real parent of the tracee.
818 to return 0 ("no wait results available yet")
819 even if the tracer knows there should be a notification.
824 ptrace(PTRACE_CONT, pid, 0L, 0L);
825 if (errno == ESRCH) {
827 r = waitpid(tracee, &status, __WALL | WNOHANG);
828 /* r can still be 0 here! */
832 .\" waitid usage? WNOWAIT?
833 .\" describe how wait notifications queue (or not queue)
835 The following kinds of ptrace-stops exist: signal-delivery-stops,
838 stops, syscall-stops.
839 They all are reported by
842 .I WIFSTOPPED(status)
844 They may be differentiated by examining the value
846 and if there is ambiguity in that value, by querying
847 .BR PTRACE_GETSIGINFO .
850 macro can't be used to perform this examination,
851 because it returns the value
852 .IR "(status>>8)\ &\ 0xff" .)
853 .SS Signal-delivery-stop
854 When a (possibly multithreaded) process receives any signal except
856 the kernel selects an arbitrary thread which handles the signal.
857 (If the signal is generated with
859 the target thread can be explicitly selected by the caller.)
860 If the selected thread is traced, it enters signal-delivery-stop.
861 At this point, the signal is not yet delivered to the process,
862 and can be suppressed by the tracer.
863 If the tracer doesn't suppress the signal,
864 it passes the signal to the tracee in the next ptrace restart request.
865 This second step of signal delivery is called
866 .I "signal injection"
868 Note that if the signal is blocked,
869 signal-delivery-stop doesn't happen until the signal is unblocked,
870 with the usual exception that
874 Signal-delivery-stop is observed by the tracer as
877 .I WIFSTOPPED(status)
878 true, with the signal returned by
879 .IR WSTOPSIG(status) .
882 this may be a different kind of ptrace-stop;
883 see the "Syscall-stops" and "execve" sections below for details.
886 returns a stopping signal, this may be a group-stop; see below.
887 .SS Signal injection and suppression
888 After signal-delivery-stop is observed by the tracer,
889 the tracer should restart the tracee with the call
891 ptrace(PTRACE_restart, pid, 0, sig)
895 is one of the restarting ptrace requests.
898 is 0, then a signal is not delivered.
899 Otherwise, the signal
902 This operation is called
903 .I "signal injection"
904 in this manual page, to distinguish it from signal-delivery-stop.
908 value may be different from the
910 value: the tracer can cause a different signal to be injected.
912 Note that a suppressed signal still causes system calls to return
914 In this case system calls will be restarted: the tracer will
915 observe the tracee to reexecute the interrupted system call (or
916 .BR restart_syscall (2)
917 system call for a few syscalls which use a different mechanism
918 for restarting) if the tracer uses
920 Even system calls (such as
922 which are not restartable after signal are restarted after
923 signal is suppressed;
924 however, kernel bugs exist which cause some syscalls to fail with
926 even though no observable signal is injected to the tracee.
928 Restarting ptrace commands issued in ptrace-stops other than
929 signal-delivery-stop are not guaranteed to inject a signal, even if
932 No error is reported; a nonzero
934 may simply be ignored.
935 Ptrace users should not try to "create a new signal" this way: use
939 The fact that signal injection requests may be ignored
940 when restarting the tracee after
941 ptrace stops that are not signal-delivery-stops
942 is a cause of confusion among ptrace users.
943 One typical scenario is that the tracer observes group-stop,
944 mistakes it for signal-delivery-stop, restarts the tracee with
946 ptrace(PTRACE_restart, pid, 0, stopsig)
948 with the intention of injecting
952 gets ignored and the tracee continues to run.
956 signal has a side effect of waking up (all threads of)
957 a group-stopped process.
958 This side effect happens before signal-delivery-stop.
959 The tracer can't suppress this side effect (it can
960 only suppress signal injection, which only causes the
962 handler to not be executed in the tracee, if such a handler is installed).
963 In fact, waking up from group-stop may be followed by
964 signal-delivery-stop for signal(s)
967 if they were pending when
972 may be not the first signal observed by the tracee after it was sent.
974 Stopping signals cause (all threads of) a process to enter group-stop.
975 This side effect happens after signal injection, and therefore can be
976 suppressed by the tracer.
978 In Linux 2.4 and earlier, the
980 signal can't be injected.
981 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
984 .\" /* The debugger continued. Ignore SIGSTOP. */
985 .\" if (signr == SIGSTOP)
989 can be used to retrieve a
991 structure which corresponds to the delivered signal.
993 may be used to modify it.
996 has been used to alter
1002 parameter in the restarting command must match,
1003 otherwise the result is undefined.
1005 When a (possibly multithreaded) process receives a stopping signal,
1007 If some threads are traced, they enter a group-stop.
1008 Note that the stopping signal will first cause signal-delivery-stop
1009 (on one tracee only), and only after it is injected by the tracer
1010 (or after it was dispatched to a thread which isn't traced),
1011 will group-stop be initiated on
1013 tracees within the multithreaded process.
1014 As usual, every tracee reports its group-stop separately
1015 to the corresponding tracer.
1017 Group-stop is observed by the tracer as
1020 .I WIFSTOPPED(status)
1021 true, with the stopping signal available via
1022 .IR WSTOPSIG(status) .
1023 The same result is returned by some other classes of ptrace-stops,
1024 therefore the recommended practice is to perform the call
1026 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
1028 The call can be avoided if the signal is not
1034 only these four signals are stopping signals.
1035 If the tracer sees something else, it can't be a group-stop.
1036 Otherwise, the tracer needs to call
1037 .BR PTRACE_GETSIGINFO .
1039 .B PTRACE_GETSIGINFO
1042 then it is definitely a group-stop.
1043 (Other failure codes are possible, such as
1045 ("no such process") if a
1050 after the tracer sees the tracee ptrace-stop and until it
1051 restarts or kills it, the tracee will not run,
1052 and will not send notifications (except
1054 death) to the tracer, even if the tracer enters into another
1058 The kernel behavior described in the previous paragraph
1059 causes a problem with transparent handling of stopping signals.
1060 If the tracer restarts the tracee after group-stop,
1062 is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
1063 If the tracer doesn't restart the tracee before entering into the next
1067 signals will not be reported to the tracer;
1068 this would cause the
1070 signals to have no effect on the tracee.
1072 Since Linux 3.4, there is a method to overcome this problem: instead of
1076 command can be used to restart a tracee in a way where it does not execute,
1077 but waits for a new event which it can report via
1080 it is restarted by a
1082 .SS PTRACE_EVENT stops
1085 options, the tracee will enter ptrace-stops called
1090 stops are observed by the tracer as
1093 .IR WIFSTOPPED(status) ,
1098 An additional bit is set in the higher byte of the status word:
1103 (SIGTRAP | PTRACE_EVENT_foo << 8).
1105 The following events exist:
1107 .B PTRACE_EVENT_VFORK
1108 Stop before return from
1115 When the tracee is continued after this stop, it will wait for child to
1116 exit/exec before continuing its execution
1117 (in other words, the usual behavior on
1120 .B PTRACE_EVENT_FORK
1121 Stop before return from
1125 with the exit signal set to
1128 .B PTRACE_EVENT_CLONE
1129 Stop before return from
1132 .B PTRACE_EVENT_VFORK_DONE
1133 Stop before return from
1140 but after the child unblocked this tracee by exiting or execing.
1142 For all four stops described above,
1143 the stop occurs in the parent (i.e., the tracee),
1144 not in the newly created thread.
1145 .BR PTRACE_GETEVENTMSG
1146 can be used to retrieve the new thread's ID.
1148 .B PTRACE_EVENT_EXEC
1149 Stop before return from
1152 .BR PTRACE_GETEVENTMSG
1153 returns the former thread ID.
1155 .B PTRACE_EVENT_EXIT
1156 Stop before exit (including death from
1157 .BR exit_group (2)),
1158 signal death, or exit caused by
1160 in a multithreaded process.
1161 .B PTRACE_GETEVENTMSG
1162 returns the exit status.
1163 Registers can be examined
1164 (unlike when "real" exit happens).
1165 The tracee is still alive; it needs to be
1168 .BR PTRACE_DETACH ed
1171 .B PTRACE_EVENT_STOP
1176 .B PTRACE_GETSIGINFO
1186 .IR "(event<<8)\ |\ SIGTRAP" .
1188 If the tracee was restarted by
1189 .BR PTRACE_SYSCALL ,
1191 syscall-enter-stop just prior to entering any system call.
1192 If the tracer restarts the tracee with
1193 .BR PTRACE_SYSCALL ,
1194 the tracee enters syscall-exit-stop when the system call is finished,
1195 or if it is interrupted by a signal.
1196 (That is, signal-delivery-stop never happens between syscall-enter-stop
1197 and syscall-exit-stop; it happens
1201 Other possibilities are that the tracee may stop in a
1203 stop, exit (if it entered
1206 .BR exit_group (2)),
1209 or die silently (if it is a thread group leader, the
1211 happened in another thread,
1212 and that thread is not traced by the same tracer;
1213 this situation is discussed later).
1215 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1218 .I WIFSTOPPED(status)
1224 .B PTRACE_O_TRACESYSGOOD
1225 option was set by the tracer, then
1228 .IR "(SIGTRAP\ |\ 0x80)" .
1230 Syscall-stops can be distinguished from signal-delivery-stop with
1233 .BR PTRACE_GETSIGINFO
1234 for the following cases:
1238 was delivered as a result of a user-space action,
1239 for example, a system call
1244 expiration of a POSIX timer,
1245 change of state on a POSIX message queue,
1246 or completion of an asynchronous I/O request.
1248 .IR si_code " == SI_KERNEL (0x80)"
1250 was sent by the kernel.
1252 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1253 This is a syscall-stop.
1255 However, syscall-stops happen very often (twice per system call),
1257 .B PTRACE_GETSIGINFO
1258 for every syscall-stop may be somewhat expensive.
1260 Some architectures allow the cases to be distinguished
1261 by examining registers.
1262 For example, on x86,
1266 in syscall-enter-stop.
1269 (like any other signal) always happens
1274 almost never contains
1278 looks like "syscall-stop which is not syscall-enter-stop";
1279 in other words, it looks like a
1280 "stray syscall-exit-stop" and can be detected this way.
1281 But such detection is fragile and is best avoided.
1284 .B PTRACE_O_TRACESYSGOOD
1285 option is the recommended method to distinguish syscall-stops
1286 from other kinds of ptrace-stops,
1287 since it is reliable and does not incur a performance penalty.
1289 Syscall-enter-stop and syscall-exit-stop are
1290 indistinguishable from each other by the tracer.
1291 The tracer needs to keep track of the sequence of
1292 ptrace-stops in order to not misinterpret syscall-enter-stop as
1293 syscall-exit-stop or vice versa.
1294 The rule is that syscall-enter-stop is
1295 always followed by syscall-exit-stop,
1297 stop or the tracee's death;
1298 no other kinds of ptrace-stop can occur in between.
1300 If after syscall-enter-stop,
1301 the tracer uses a restarting command other than
1302 .BR PTRACE_SYSCALL ,
1303 syscall-exit-stop is not generated.
1305 .B PTRACE_GETSIGINFO
1306 on syscall-stops returns
1315 .IR (SIGTRAP|0x80) .
1316 .SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops
1317 [Details of these kinds of stops are yet to be documented.]
1320 .\" document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
1321 .\" PTRACE_SYSEMU_SINGLESTEP
1322 .SS Informational and restarting ptrace commands
1323 Most ptrace commands (all except
1326 .BR PTRACE_TRACEME ,
1327 .BR PTRACE_INTERRUPT ,
1330 require the tracee to be in a ptrace-stop, otherwise they fail with
1333 When the tracee is in ptrace-stop,
1334 the tracer can read and write data to
1335 the tracee using informational commands.
1336 These commands leave the tracee in ptrace-stopped state:
1339 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1340 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1341 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1342 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1343 ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);
1344 ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);
1345 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1346 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1347 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
1348 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1351 Note that some errors are not reported.
1352 For example, setting signal information
1354 may have no effect in some ptrace-stops, yet the call may succeed
1355 (return 0 and not set
1358 .B PTRACE_GETEVENTMSG
1359 may succeed and return some random value if current ptrace-stop
1360 is not documented as returning a meaningful event message.
1364 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1367 The tracee's current flags are replaced.
1368 Flags are inherited by new tracees created and "auto-attached" via active
1369 .BR PTRACE_O_TRACEFORK ,
1370 .BR PTRACE_O_TRACEVFORK ,
1372 .BR PTRACE_O_TRACECLONE
1375 Another group of commands makes the ptrace-stopped tracee run.
1378 ptrace(cmd, pid, 0, sig);
1386 .BR PTRACE_SYSCALL ,
1387 .BR PTRACE_SINGLESTEP ,
1390 .BR PTRACE_SYSEMU_SINGLESTEP .
1391 If the tracee is in signal-delivery-stop,
1393 is the signal to be injected (if it is nonzero).
1397 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
1398 recommended practice is to always pass 0 in
1400 .SS Attaching and detaching
1401 A thread can be attached to the tracer using the call
1403 ptrace(PTRACE_ATTACH, pid, 0, 0);
1407 ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
1413 If the tracer wants this
1415 to have no effect, it needs to suppress it.
1416 Note that if other signals are concurrently sent to
1417 this thread during attach,
1418 the tracer may see the tracee enter signal-delivery-stop
1419 with other signal(s) first!
1420 The usual practice is to reinject these signals until
1422 is seen, then suppress
1425 The design bug here is that a ptrace attach and a concurrently delivered
1427 may race and the concurrent
1431 .\" FIXME: Describe how to attach to a thread which is already
1434 Since attaching sends
1436 and the tracer usually suppresses it, this may cause a stray
1438 return from the currently executing system call in the tracee,
1439 as described in the "Signal injection and suppression" section.
1443 can be used instead of
1446 does not stop the attached process. If you need to stop
1447 it after attach (or at any other time) without sending it any signals,
1454 ptrace(PTRACE_TRACEME, 0, 0, 0);
1456 turns the calling thread into a tracee.
1457 The thread continues to run (doesn't enter ptrace-stop).
1458 A common practice is to follow the
1464 and allow the parent (which is our tracer now) to observe our
1465 signal-delivery-stop.
1468 .BR PTRACE_O_TRACEFORK ,
1469 .BR PTRACE_O_TRACEVFORK ,
1471 .BR PTRACE_O_TRACECLONE
1472 options are in effect, then children created by, respectively,
1482 with the exit signal set to
1486 are automatically attached to the same tracer which traced their parent.
1488 is delivered to the children, causing them to enter
1489 signal-delivery-stop after they exit the system call which created them.
1491 Detaching of the tracee is performed by:
1493 ptrace(PTRACE_DETACH, pid, 0, sig);
1496 is a restarting operation;
1497 therefore it requires the tracee to be in ptrace-stop.
1498 If the tracee is in signal-delivery-stop, a signal can be injected.
1501 parameter may be silently ignored.
1503 If the tracee is running when the tracer wants to detach it,
1504 the usual solution is to send
1508 to make sure it goes to the correct thread),
1509 wait for the tracee to stop in signal-delivery-stop for
1511 and then detach it (suppressing
1514 A design bug is that this can race with concurrent
1516 Another complication is that the tracee may enter other ptrace-stops
1517 and needs to be restarted and waited for again, until
1520 Yet another complication is to be sure that
1521 the tracee is not already ptrace-stopped,
1522 because no signal delivery happens while it is\(emnot even
1524 .\" FIXME: Describe how to detach from a group-stopped tracee so that it
1525 .\" doesn't run, but continues to wait for SIGCONT.
1527 If the tracer dies, all tracees are automatically detached and restarted,
1528 unless they were in group-stop.
1529 Handling of restart from group-stop is currently buggy,
1530 but the "as planned" behavior is to leave tracee stopped and waiting for
1532 If the tracee is restarted from signal-delivery-stop,
1533 the pending signal is injected.
1534 .SS execve(2) under ptrace
1535 .\" clone(2) CLONE_THREAD says:
1536 .\" If any of the threads in a thread group performs an execve(2),
1537 .\" then all threads other than the thread group leader are terminated,
1538 .\" and the new program is executed in the thread group leader.
1540 When one thread in a multithreaded process calls
1542 the kernel destroys all other threads in the process,
1543 .\" In kernel 3.1 sources, see fs/exec.c::de_thread()
1544 and resets the thread ID of the execing thread to the
1545 thread group ID (process ID).
1546 (Or, to put things another way, when a multithreaded process does an
1548 at completion of the call, it appears as though the
1550 occurred in the thread group leader, regardless of which thread did the
1552 This resetting of the thread ID looks very confusing to tracers:
1554 All other threads stop in
1555 .B PTRACE_EVENT_EXIT
1557 .BR PTRACE_O_TRACEEXIT
1558 option was turned on.
1559 Then all other threads except the thread group leader report
1560 death as if they exited via
1564 The execing tracee changes its thread ID while it is in the
1566 (Remember, under ptrace, the "pid" returned from
1568 or fed into ptrace calls, is the tracee's thread ID.)
1569 That is, the tracee's thread ID is reset to be the same as its process ID,
1570 which is the same as the thread group leader's thread ID.
1573 .B PTRACE_EVENT_EXEC
1574 stop happens, if the
1575 .BR PTRACE_O_TRACEEXEC
1576 option was turned on.
1578 If the thread group leader has reported its
1579 .B PTRACE_EVENT_EXIT
1581 it appears to the tracer that
1582 the dead thread leader "reappears from nowhere".
1583 (Note: the thread group leader does not report death via
1584 .I WIFEXITED(status)
1585 until there is at least one other live thread.
1586 This eliminates the possibility that the tracer will see
1587 it dying and then reappearing.)
1588 If the thread group leader was still alive,
1589 for the tracer this may look as if thread group leader
1590 returns from a different system call than it entered,
1591 or even "returned from a system call even though
1592 it was not in any system call".
1593 If the thread group leader was not traced
1594 (or was traced by a different tracer), then during
1596 it will appear as if it has become a tracee of
1597 the tracer of the execing tracee.
1599 All of the above effects are the artifacts of
1600 the thread ID change in the tracee.
1603 .B PTRACE_O_TRACEEXEC
1604 option is the recommended tool for dealing with this situation.
1606 .BR PTRACE_EVENT_EXEC
1611 In this stop, the tracer can use
1612 .B PTRACE_GETEVENTMSG
1613 to retrieve the tracee's former thread ID.
1614 (This feature was introduced in Linux 3.0).
1616 .B PTRACE_O_TRACEEXEC
1617 option disables legacy
1622 When the tracer receives
1623 .B PTRACE_EVENT_EXEC
1625 it is guaranteed that except this tracee and the thread group leader,
1626 no other threads from the process are alive.
1629 .B PTRACE_EVENT_EXEC
1631 the tracer should clean up all its internal
1632 data structures describing the threads of this process,
1633 and retain only one data structure\(emone which
1634 describes the single still running tracee, with
1636 thread ID == thread group ID == process ID.
1638 Example: two threads call
1643 *** we get syscall-enter-stop in thread 1: **
1644 PID1 execve("/bin/foo", "foo" <unfinished ...>
1645 *** we issue PTRACE_SYSCALL for thread 1 **
1646 *** we get syscall-enter-stop in thread 2: **
1647 PID2 execve("/bin/bar", "bar" <unfinished ...>
1648 *** we issue PTRACE_SYSCALL for thread 2 **
1649 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
1650 *** we get syscall-exit-stop for PID0: **
1651 PID0 <... execve resumed> ) = 0
1655 .B PTRACE_O_TRACEEXEC
1658 in effect for the execing tracee, the kernel delivers an extra
1663 This is an ordinary signal (similar to one which can be
1666 not a special kind of ptrace-stop.
1668 .B PTRACE_GETSIGINFO
1669 for this signal returns
1673 This signal may be blocked by signal mask,
1674 and thus may be delivered (much) later.
1676 Usually, the tracer (for example,
1678 would not want to show this extra post-execve
1680 signal to the user, and would suppress its delivery to the tracee (if
1684 it is a killing signal).
1685 However, determining
1688 to suppress is not easy.
1690 .B PTRACE_O_TRACEEXEC
1691 option and thus suppressing this extra
1693 is the recommended approach.
1695 The ptrace API (ab)uses the standard UNIX parent/child signaling over
1697 This used to cause the real parent of the process to stop receiving
1700 notifications when the child process is traced by some other process.
1702 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
1703 exist; see BUGS below.
1705 As of Linux 2.6.38, the following is believed to work correctly:
1707 exit/death by signal is reported first to the tracer, then,
1708 when the tracer consumes the
1710 result, to the real parent (to the real parent only when the
1711 whole multithreaded process exits).
1712 If the tracer and the real parent are the same process,
1713 the report is sent only once.
1717 requests return the requested data,
1718 while other requests return zero.
1719 On error, all requests return \-1, and
1721 is set appropriately.
1722 Since the value returned by a successful
1724 request may be \-1, the caller must clear
1726 before the call, and then check it afterward
1727 to determine whether or not an error occurred.
1731 (i386 only) There was an error with allocating or freeing a debug register.
1734 There was an attempt to read from or write to an invalid area in
1735 the tracer's or the tracee's memory,
1736 probably because the area wasn't mapped or accessible.
1737 Unfortunately, under Linux, different variations of this fault
1742 more or less arbitrarily.
1745 An attempt was made to set an invalid option.
1749 is invalid, or an attempt was made to read from or
1750 write to an invalid area in the tracer's or the tracee's memory,
1751 or there was a word-alignment violation,
1752 or an invalid signal was specified during a restart request.
1755 The specified process cannot be traced.
1756 This could be because the
1757 tracer has insufficient privileges (the required capability is
1758 .BR CAP_SYS_PTRACE );
1759 unprivileged processes cannot trace processes that they
1760 cannot send signals to or those running
1761 set-user-ID/set-group-ID programs, for obvious reasons.
1762 Alternatively, the process may already be being traced,
1763 or (on kernels before 2.6.26) be
1768 The specified process does not exist, or is not currently being traced
1769 by the caller, or is not stopped
1770 (for requests that require a stopped tracee).
1774 Although arguments to
1776 are interpreted according to the prototype given,
1777 glibc currently declares
1779 as a variadic function with only the
1782 It is recommended to always supply four arguments,
1783 even if the requested operation does not use them,
1784 setting unused/ignored arguments to
1789 In Linux kernels before 2.6.26,
1790 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
1792 the process with PID 1, may not be traced.
1794 The layout of the contents of memory and the USER area are
1795 quite operating-system- and architecture-specific.
1796 The offset supplied, and the data returned,
1797 might not entirely match with the definition of
1799 .\" See http://lkml.org/lkml/2008/5/8/375
1801 The size of a "word" is determined by the operating-system variant
1802 (e.g., for 32-bit Linux it is 32 bits).
1804 This page documents the way the
1806 call works currently in Linux.
1807 Its behavior differs noticeably on other flavors of UNIX.
1810 is highly specific to the operating system and architecture.
1812 On hosts with 2.6 kernel headers,
1813 .B PTRACE_SETOPTIONS
1814 is declared with a different value than the one for 2.4.
1815 This leads to applications compiled with 2.6 kernel
1816 headers failing when run on 2.4 kernels.
1817 This can be worked around by redefining
1818 .B PTRACE_SETOPTIONS
1820 .BR PTRACE_OLDSETOPTIONS ,
1823 Group-stop notifications are sent to the tracer, but not to real parent.
1824 Last confirmed on 2.6.38.6.
1826 If a thread group leader is traced and exits by calling
1828 .\" Note from Denys Vlasenko:
1829 .\" Here "exits" means any kind of death - _exit, exit_group,
1830 .\" signal death. Signal death and exit_group cases are trivial,
1831 .\" though: since signal death and exit_group kill all other threads
1832 .\" too, "until all other threads exit" thing happens rather soon
1833 .\" in these cases. Therefore, only _exit presents observably
1834 .\" puzzling behavior to ptrace users: thread leader _exit's,
1835 .\" but WIFEXITED isn't reported! We are trying to explain here
1838 .B PTRACE_EVENT_EXIT
1839 stop will happen for it (if requested), but the subsequent
1841 notification will not be delivered until all other threads exit.
1842 As explained above, if one of other threads calls
1844 the death of the thread group leader will
1847 If the execed thread is not traced by this tracer,
1848 the tracer will never know that
1851 One possible workaround is to
1853 the thread group leader instead of restarting it in this case.
1854 Last confirmed on 2.6.38.6.
1855 .\" FIXME: ^^^ need to test/verify this scenario
1859 signal may still cause a
1860 .B PTRACE_EVENT_EXIT
1861 stop before actual signal death.
1862 This may be changed in the future;
1864 is meant to always immediately kill tasks even under ptrace.
1865 Last confirmed on 2.6.38.6.
1867 Some system calls return with
1869 if a signal was sent to a tracee, but delivery was suppressed by the tracer.
1870 (This is very typical operation: it is usually
1871 done by debuggers on every attach, in order to not introduce
1874 As of Linux 3.2.9, the following system calls are affected
1875 (this list is likely incomplete):
1882 The usual symptom of this bug is that when you attach to
1883 a quiescent process with the command
1885 strace -p <process-ID>
1887 then, instead of the usual
1888 and expected one-line output such as
1891 restart_syscall(<... resuming interrupted call ...>_
1897 select(6, [5], NULL, [5], NULL_
1900 ('_' denotes the cursor position), you observe more than one line.
1904 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
1908 What is not visible here is that the process was blocked in
1915 to return to user space with the error
1917 In this particular case, the program reacted to
1919 by checking the current time, and then executing
1922 (Programs which do not expect such "stray"
1924 errors may behave in an unintended way upon an
1939 .BR capabilities (7),