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 .\" FIXME (later): Linux 3.1 adds PTRACE_SEIZE, PTRACE_INTERRUPT,
46 .\" and PTRACE_LISTEN.
48 .TH PTRACE 2 2012-03-06 "Linux" "Linux Programmer's Manual"
50 ptrace \- process trace
53 .B #include <sys/ptrace.h>
55 .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
56 .BI " void *" addr ", void *" data );
61 system call provides a means by which one process (the "tracer")
62 may observe and control the execution of another process (the "tracee"),
63 and examine and change the tracee's memory and registers.
64 It is primarily used to implement breakpoint debugging and system
67 A tracee first needs to be attached to the tracer.
68 Attachment and subsequent commands are per thread:
69 in a multithreaded process,
70 every thread can be individually attached to a
71 (potentially different) tracer,
72 or left not attached and thus not debugged.
73 Therefore, "tracee" always means "(one) thread",
74 never "a (possibly multithreaded) process".
75 Ptrace commands are always sent to
76 a specific tracee using a call of the form
78 ptrace(PTRACE_foo, pid, ...)
82 is the thread ID of the corresponding Linux thread.
84 (Note that in this page, a "multithreaded process"
85 means a thread group consisting of threads created using the
90 A process can initiate a trace by calling
92 and having the resulting child do a
94 followed (typically) by an
96 Alternatively, one process may commence tracing another process using
99 While being traced, the tracee will stop each time a signal is delivered,
100 even if the signal is being ignored.
103 which has its usual effect.)
104 The tracer will be notified at its next call to
106 (or one of the related "wait" system calls); that call will return a
108 value containing information that indicates
109 the cause of the stop in the tracee.
110 While the tracee is stopped,
111 the tracer can use various ptrace requests to inspect and modify the tracee.
112 The tracer then causes the tracee to continue,
113 optionally ignoring the delivered signal
114 (or even delivering a different signal instead).
116 When the tracer is finished tracing, it can cause the tracee to continue
117 executing in a normal, untraced mode via
122 determines the action to be performed:
125 Indicate that this process is to be traced by its parent.
128 delivered to this process will cause it to stop and its
129 parent to be notified via
131 In addition, all subsequent calls to
133 by the traced process will cause a
136 giving the parent a chance to gain control before the new program
138 A process probably shouldn't make this request if its parent
139 isn't expecting to trace it.
148 request is used only by the tracee;
149 the remaining requests are used only by the tracer.
150 In the following requests,
152 specifies the thread ID of the tracee to be acted on.
153 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 userspace 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.
225 .BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
226 Retrieve information about the signal that caused the stop.
231 from the tracee to the address
237 .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
238 Copy the tracee's general-purpose or floating-point registers,
239 respectively, from the address
243 .BR PTRACE_POKEUSER ,
244 some general-purpose register modifications may be disallowed.
245 .\" FIXME In the preceding sentence, which modifications are disallowed,
246 .\" and when they are disallowed, how does userspace discover that fact?
250 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
251 Set signal information:
254 structure from the address
256 in the tracer to the tracee.
257 This will affect only signals that would normally be delivered to
258 the tracee and were caught by the tracer.
259 It may be difficult to tell
260 these normal signals from synthetic signals generated by
266 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
267 Set ptrace options from
272 is interpreted as a bit mask of options,
273 which are specified by the following flags:
276 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
277 When delivering system call traps, set bit 7 in the signal number
279 .IR "SIGTRAP|0x80" ).
280 This makes it easy for the tracer to distinguish
281 normal traps from those caused by a system call.
282 .RB ( PTRACE_O_TRACESYSGOOD
283 may not work on all architectures.)
285 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
286 Stop the tracee at the next
288 and automatically start tracing the newly forked process,
289 which will start with a
293 by the tracer will return a
298 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
301 The PID of the new process can be retrieved with
302 .BR PTRACE_GETEVENTMSG .
304 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
305 Stop the tracee at the next
307 and automatically start tracing the newly vforked process,
308 which will start with a
312 by the tracer will return a
317 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
320 The PID of the new process can be retrieved with
321 .BR PTRACE_GETEVENTMSG .
323 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
324 Stop the tracee at the next
326 and automatically start tracing the newly cloned process,
327 which will start with a
331 by the tracer will return a
336 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
339 The PID of the new process can be retrieved with
340 .BR PTRACE_GETEVENTMSG .
342 This option may not catch
350 .B PTRACE_EVENT_VFORK
351 will be delivered instead
353 .B PTRACE_O_TRACEVFORK
354 is set; otherwise if the tracee calls
356 with the exit signal set to
360 .B PTRACE_O_TRACEFORK
363 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
364 Stop the tracee at the next
368 by the tracer will return a
373 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
377 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
378 Stop the tracee at the completion of the next
382 by the tracer will return a
387 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
390 The PID of the new process can (since Linux 2.6.18) be retrieved with
391 .BR PTRACE_GETEVENTMSG .
393 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
394 Stop the tracee at exit.
397 by the tracer will return a
402 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
405 The tracee's exit status can be retrieved with
406 .BR PTRACE_GETEVENTMSG .
408 The tracee is stopped early during process exit,
409 when registers are still available,
410 allowing the tracer to see where the exit occurred,
411 whereas the normal exit notification is done after the process
413 Even though context is available,
414 the tracer cannot prevent the exit from happening at this point.
417 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
418 Retrieve a message (as an
419 .IR "unsigned long" )
420 about the ptrace event
421 that just happened, placing it at the address
425 .BR PTRACE_EVENT_EXIT ,
426 this is the tracee's exit status.
428 .BR PTRACE_EVENT_FORK ,
429 .BR PTRACE_EVENT_VFORK ,
430 .BR PTRACE_EVENT_VFORK_DONE ,
432 .BR PTRACE_EVENT_CLONE ,
433 this is the PID of the new process.
438 Restart the stopped tracee process.
442 it is interpreted as the number of a signal to be delivered to the tracee;
443 otherwise, no signal is delivered.
444 Thus, for example, the tracer can control
445 whether a signal sent to the tracee is delivered or not.
449 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
450 Restart the stopped tracee as for
452 but arrange for the tracee to be stopped at
453 the next entry to or exit from a system call,
454 or after execution of a single instruction, respectively.
455 (The tracee will also, as usual, be stopped upon receipt of a signal.)
456 From the tracer's perspective, the tracee will appear to have been
457 stopped by receipt of a
461 for example, the idea is to inspect
462 the arguments to the system call at the first stop,
465 and inspect the return value of the system call at the second stop.
468 argument is treated as for
473 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
476 continue and stop on entry to the next system call,
477 which will not be executed.
479 .BR PTRACE_SYSEMU_SINGLESTEP ,
480 do the same but also singlestep if not a system call.
481 This call is used by programs like
482 User Mode Linux that want to emulate all the tracee's system calls.
485 argument is treated as for
489 not supported on all architectures.)
500 .I This operation is deprecated; do not use it!
509 is that it requires the tracee to be in signal-delivery-stop,
510 otherwise it may not work
511 (i.e., may complete successfully but won't kill the tracee).
512 By contrast, sending a
514 directly has no such limitation.
515 .\" [Note from Denys Vlasenko:
516 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
517 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
520 Attach to the process specified in
522 making it a tracee of the calling process.
523 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
524 .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
525 .\" Basically, it's not true for any Linux in practical use.
526 .\" ; the behavior of the tracee is as if it had done a
527 .\" .BR PTRACE_TRACEME .
528 .\" The calling process actually becomes the parent of the tracee
529 .\" process for most purposes (e.g., it will receive
530 .\" notification of tracee events and appears in
532 .\" output as the tracee's parent), but a
534 .\" by the tracee will still return the PID of the original parent.
537 but will not necessarily have stopped
538 by the completion of this call; use
540 to wait for the tracee to stop.
541 See the "Attaching and detaching" subsection for additional information.
548 Restart the stopped tracee as for
550 but first detach from it.
551 Under Linux, a tracee can be detached in this way regardless
552 of which method was used to initiate tracing.
556 .\" In the text below, we decided to avoid prettifying the text with markup:
557 .\" it would make the source nearly impossible to edit, and we _do_ intend
558 .\" to edit it often, in order to keep it updated:
559 .\" ptrace API is full of quirks, no need to compound this situation by
560 .\" making it excruciatingly painful to document them!
562 .SS Death under ptrace
563 When a (possibly multithreaded) process receives a killing signal
564 (one whose disposition is set to
566 and whose default action is to kill the process),
568 Tracees report their death to their tracer(s).
569 Notification of this event is delivered via
572 Note that the killing signal will first cause signal-delivery-stop
573 (on one tracee only),
574 and only after it is injected by the tracer
575 (or after it was dispatched to a thread which isn't traced),
576 will death from the signal happen on
578 tracees within a multithreaded process.
579 (The term "signal-delivery-stop" is explained below.)
582 operates similarly, with exceptions.
583 No signal-delivery-stop is generated for
585 and therefore the tracer can't suppress it.
587 kills even within system calls
588 (syscall-exit-stop is not generated prior to death by
590 The net effect is that
592 always kills the process (all its threads),
593 even if some threads of the process are ptraced.
595 When the tracee calls
597 it reports its death to its tracer.
598 Other threads are not affected.
600 When any thread executes
602 every tracee in its thread group reports its death to its tracer.
605 .B PTRACE_O_TRACEEXIT
608 will happen before actual death.
609 This applies to exits via
612 and signal deaths (except
614 and when threads are torn down on
616 in a multithreaded process.
618 The tracer cannot assume that the ptrace-stopped tracee exists.
619 There are many scenarios when the tracee may die while stopped (such as
621 Therefore, the tracer must be prepared to handle an
623 error on any ptrace operation.
624 Unfortunately, the same error is returned if the tracee
625 exists but is not ptrace-stopped
626 (for commands which require a stopped tracee),
627 or if it is not traced by the process which issued the ptrace call.
628 The tracer needs to keep track of the stopped/running state of the tracee,
631 as "tracee died unexpectedly" only if it knows that the tracee has
632 been observed to enter ptrace-stop.
633 Note that there is no guarantee that
635 will reliably report the tracee's death status if a
636 ptrace operation returned
639 may return 0 instead.
640 In other words, the tracee may be "not yet fully dead",
641 but already refusing ptrace requests.
643 The tracer can't assume that the tracee
645 ends its life by reporting
648 .IR WIFSIGNALED(status) ;
649 there are cases where this does not occur.
650 For example, if a thread other than thread group leader does an
653 its PID will never be seen again,
654 and any subsequent ptrace stops will be reported under
655 the thread group leader's PID.
657 A tracee can be in two states: running or stopped.
659 There are many kinds of states when the tracee is stopped, and in ptrace
660 discussions they are often conflated.
661 Therefore, it is important to use precise terms.
663 In this manual page, any stopped state in which the tracee is ready
664 to accept ptrace commands from the tracer is called
667 be further subdivided into
668 .IR signal-delivery-stop ,
672 These stopped states are described in detail below.
674 When the running tracee enters ptrace-stop, it notifies its tracer using
676 (or one of the other "wait" system calls).
677 Most of this manual page assumes that the tracer waits with:
679 pid = waitpid(pid_or_minus_1, &status, __WALL);
681 Ptrace-stopped tracees are reported as returns with
684 .I WIFSTOPPED(status)
687 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
688 .\" I am not 100% sure there aren't ugly corner cases.) Are the
689 .\" rules different if user wants to use waitid? Will waitid require
695 flag does not include the
699 flags, but implies their functionality.
705 is not recommended: the "continued" state is per-process and
706 consuming it can confuse the real parent of the tracee.
712 to return 0 ("no wait results available yet")
713 even if the tracer knows there should be a notification.
717 kill(tracee, SIGKILL);
718 waitpid(tracee, &status, __WALL | WNOHANG);
721 .\" waitid usage? WNOWAIT?
722 .\" describe how wait notifications queue (or not queue)
724 The following kinds of ptrace-stops exist: signal-delivery-stops,
725 group-stop, PTRACE_EVENT stops, syscall-stops
726 .BR PTRACE_SINGLESTEP ,
729 .BE PTRACE_SYSEMU_SINGLESTEP .
730 They all are reported by
733 .I WIFSTOPPED(status)
735 They may be differentiated by examining the value
737 and if there is ambiguity in that value, by querying
738 .BR PTRACE_GETSIGINFO .
741 macro can't be used to perform this examination,
742 because it returns the value
743 (\fIstatus\>>8)\ \fB&\ 0xff\fP\fP.)
744 .SS Signal-delivery-stop
745 When a (possibly multithreaded) process receives any signal except
747 the kernel selects an arbitrary thread which handles the signal.
748 (If the signal is generated with
750 the target thread can be explicitly selected by the caller.)
751 If the selected thread is traced, it enters signal-delivery-stop.
752 At this point, the signal is not yet delivered to the process,
753 and can be suppressed by the tracer.
754 If the tracer doesn't suppress the signal,
755 it passes the signal to the tracee in the next ptrace restart request.
756 This second step of signal delivery is called
757 .I "signal injection"
759 Note that if the signal is blocked,
760 signal-delivery-stop doesn't happen until the signal is unblocked,
761 with the usual exception that
765 Signal-delivery-stop is observed by the tracer as
768 .I WIFSTOPPED(status)
769 true, with the stopping signal returned by
770 .IR WSTOPSIG(status) .
771 If the stopping signal is
773 this may be a different kind of ptrace-stop;
774 see the "Syscall-stops" and "execve" sections below for details.
777 returns a stopping signal, this may be a group-stop; see below.
778 .SS Signal injection and suppression
779 After signal-delivery-stop is observed by the tracer,
780 the tracer should restart the tracee with the call
782 ptrace(PTRACE_restart, pid, 0, sig)
786 is one of the restarting ptrace requests.
789 is 0, then a signal is not delivered.
790 Otherwise, the signal
793 This operation is called
794 .I "signal injection"
795 in this manual page, to distinguish it from signal-delivery-stop.
799 value may be different from the
801 value: the tracer can cause a different signal to be injected.
803 Note that a suppressed signal still causes system calls to return
805 Restartable system calls will be restarted (the tracer will
806 observe the tracee to execute
807 .BR restart_syscall(2)
809 .BR PTRACE_SYSCALL );
810 non-restartable system calls may fail with
812 even though no observable signal is injected to the tracee.
814 Restarting ptrace commands issued in ptrace-stops other than
815 signal-delivery-stop are not guaranteed to inject a signal, even if
818 No error is reported; a nonzero
820 may simply be ignored.
821 Ptrace users should not try to "create a new signal" this way: use
825 The fact that signal injection requests may be ignored
826 when restarting the tracee after
827 ptrace stops that are not signal-delivery-stops
828 is a cause of confusion among ptrace users.
829 One typical scenario is that the tracer observes group-stop,
830 mistakes it for signal-delivery-stop, restarts the tracee with
832 ptrace(PTRACE_rest, pid, 0, stopsig)
834 with the intention of injecting
838 gets ignored and the tracee continues to run.
842 signal has a side effect of waking up (all threads of)
843 a group-stopped process.
844 This side effect happens before signal-delivery-stop.
845 The tracer can't suppress this side-effect (it can
846 only suppress signal injection, which only causes the
848 handler to not be executed in the tracee, if such a handler is installed).
849 In fact, waking up from group-stop may be followed by
850 signal-delivery-stop for signal(s)
853 if they were pending when
858 may be not the first signal observed by the tracee after it was sent.
860 Stopping signals cause (all threads of) a process to enter group-stop.
861 This side effect happens after signal injection, and therefore can be
862 suppressed by the tracer.
864 In Linux 2.4 and earlier, the
866 signal can't be injected.
867 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
870 .\" /* The debugger continued. Ignore SIGSTOP. */
871 .\" if (signr == SIGSTOP)
875 can be used to retrieve a
877 structure which corresponds to the delivered signal.
879 may be used to modify it.
882 has been used to alter
888 parameter in the restarting command must match,
889 otherwise the result is undefined.
891 When a (possibly multithreaded) process receives a stopping signal,
893 If some threads are traced, they enter a group-stop.
894 Note that the stopping signal will first cause signal-delivery-stop
895 (on one tracee only), and only after it is injected by the tracer
896 (or after it was dispatched to a thread which isn't traced),
897 will group-stop be initiated on
899 tracees within the multithreaded process.
900 As usual, every tracee reports its group-stop separately
901 to the corresponding tracer.
903 Group-stop is observed by the tracer as
906 .I WIFSTOPPED(status)
907 true, with the stopping signal available via
908 .IR WSTOPSIG(status) .
909 The same result is returned by some other classes of ptrace-stops,
910 therefore the recommended practice is to perform the call
912 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
914 The call can be avoided if the signal is not
920 only these four signals are stopping signals.
921 If the tracer sees something else, it can't be a group-stop.
922 Otherwise, the tracer needs to call
923 .BR PTRACE_GETSIGINFO .
928 then it is definitely a group-stop.
929 (Other failure codes are possible, such as
931 ("no such process") if a
936 after the tracer sees the tracee ptrace-stop and until it
937 restarts or kills it, the tracee will not run,
938 and will not send notifications (except
940 death) to the tracer, even if the tracer enters into another
944 The kernel behavior described in the previous paragraph
945 causes a problem with transparent handling of stopping signals.
946 If the tracer restarts the tracee after group-stop,
948 is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
949 If the tracer doesn't restart the tracee before entering into the next
953 signals will not be reported to the tracer;
956 signals to have no effect on the tracee.
957 .SS PTRACE_EVENT stops
960 options, the tracee will enter ptrace-stops called
965 stops are observed by the tracer as
968 .IR WIFSTOPPED(status) ,
973 An additional bit is set in the higher byte of the status word:
978 (SIGTRAP | PTRACE_EVENT_foo << 8).
980 The following events exist:
982 .B PTRACE_EVENT_VFORK
983 Stop before return from
990 When the tracee is continued after this stop, it will wait for child to
991 exit/exec before continuing its execution
992 (in other words, the usual behavior on
996 Stop before return from
1000 with the exit signal set to
1003 .B PTRACE_EVENT_CLONE
1004 Stop before return from
1007 .B PTRACE_EVENT_VFORK_DONE
1008 Stop before return from
1015 but after the child unblocked this tracee by exiting or execing.
1017 For all four stops described above,
1018 the stop occurs in the parent (i.e., the tracee),
1019 not in the newly created thread.
1020 .BR PTRACE_GETEVENTMSG
1021 can be used to retrieve the new thread's ID.
1023 .B PTRACE_EVENT_EXEC
1024 Stop before return from
1027 .B PTRACE_EVENT_EXIT
1028 Stop before exit (including death from
1029 .BR exit_group (2)),
1030 signal death, or exit caused by
1032 in a multithreaded process.
1033 .B PTRACE_GETEVENTMSG
1034 returns the exit status.
1035 Registers can be examined
1036 (unlike when "real" exit happens).
1037 The tracee is still alive; it needs to be
1040 .BR PTRACE_DETACH ed
1043 .B PTRACE_GETSIGINFO
1052 .IR "(event<<8)\ |\ SIGTRAP" .
1054 If the tracee was restarted by
1055 .BR PTRACE_SYSCALL ,
1057 syscall-enter-stop just prior to entering any system call.
1058 If the tracer restarts the tracee with
1059 .BR PTRACE_SYSCALL ,
1060 the tracee enters syscall-exit-stop when the system call is finished,
1061 or if it is interrupted by a signal.
1062 (That is, signal-delivery-stop never happens between syscall-enter-stop
1063 and syscall-exit-stop; it happens
1067 Other possibilities are that the tracee may stop in a
1069 stop, exit (if it entered
1072 .BR exit_group (2)),
1075 or die silently (if it is a thread group leader, the
1077 happened in another thread,
1078 and that thread is not traced by the same tracer;
1079 this situation is discussed later).
1081 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1084 .I WIFSTOPPED(status)
1090 .B PTRACE_O_TRACESYSGOOD
1091 option was set by the tracer, then
1094 .IR "(SIGTRAP\ |\ 0x80)" .
1096 Syscall-stops can be distinguished from signal-delivery-stop with
1099 .BR PTRACE_GETSIGINFO
1100 for the following cases:
1104 was delivered as a result of a userspace action,
1105 for example, a system call
1110 expiration of a POSIX timer,
1111 change of state on a POSIX message queue,
1112 or completion of an asynchronous I/O request.
1114 .IR si_code " == SI_KERNEL (0x80)"
1116 was sent by the kernel.
1118 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1119 This is a syscall-stop.
1121 However, syscall-stops happen very often (twice per system call),
1123 .B PTRACE_GETSIGINFO
1124 for every syscall-stop may be somewhat expensive.
1126 Some architectures allow the cases to be distinguished
1127 by examining registers.
1128 For example, on x86,
1132 in syscall-enter-stop.
1135 (like any other signal) always happens
1140 almost never contains
1144 looks like "syscall-stop which is not syscall-enter-stop";
1145 in other words, it looks like a
1146 "stray syscall-exit-stop" and can be detected this way.
1147 But such detection is fragile and is best avoided.
1150 .B PTRACE_O_TRACESYSGOOD
1151 option is the recommended method to distinquish syscall-stops
1152 from other kinds of ptrace-stops,
1153 since it is reliable and does not incur a performance penalty.
1155 Syscall-enter-stop and syscall-exit-stop are
1156 indistinguishable from each other by the tracer.
1157 The tracer needs to keep track of the sequence of
1158 ptrace-stops in order to not misinterpret syscall-enter-stop as
1159 syscall-exit-stop or vice versa.
1160 The rule is that syscall-enter-stop is
1161 always followed by syscall-exit-stop,
1163 stop or the tracee's death;
1164 no other kinds of ptrace-stop can occur in between.
1166 If after syscall-enter-stop,
1167 the tracer uses a restarting command other than
1168 .BR PTRACE_SYSCALL ,
1169 syscall-exit-stop is not generated.
1171 .B PTRACE_GETSIGINFO
1172 on syscall-stops returns
1181 .IR (SIGTRAP|0x80) .
1182 .SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops
1183 [Details of these kinds of stops are yet to be documented.]
1186 .\" document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
1187 .\" PTRACE_SYSEMU_SINGLESTEP
1188 .SS Informational and restarting ptrace commands
1189 Most ptrace commands (all except
1191 .BR PTRACE_TRACEME ,
1194 require the tracee to be in a ptrace-stop, otherwise they fail with
1197 When the tracee is in ptrace-stop,
1198 the tracer can read and write data to
1199 the tracee using informational commands.
1200 These commands leave the tracee in ptrace-stopped state:
1203 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1204 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1205 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1206 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1207 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1208 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1209 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
1210 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1213 Note that some errors are not reported.
1214 For example, setting signal information
1216 may have no effect in some ptrace-stops, yet the call may succeed
1217 (return 0 and not set
1220 .B PTRACE_GETEVENTMSG
1221 may succeed and return some random value if current ptrace-stop
1222 is not documented as returning a meaningful event message.
1226 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1229 The tracee's current flags are replaced.
1230 Flags are inherited by new tracees created and "auto-attached" via active
1231 .BR PTRACE_O_TRACEFORK ,
1232 .BR PTRACE_O_TRACEVFORK ,
1234 .BR PTRACE_O_TRACECLONE
1237 Another group of commands makes the ptrace-stopped tracee run.
1240 ptrace(cmd, pid, 0, sig);
1247 .BR PTRACE_SYSCALL ,
1248 .BR PTRACE_SINGLESTEP ,
1251 .BR PTRACE_SYSEMU_SINGLESTEP.
1252 If the tracee is in signal-delivery-stop,
1254 is the signal to be injected (if it is nonzero).
1258 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
1259 recommended practice is to always pass 0 in
1261 .SS Attaching and detaching
1262 A thread can be attached to the tracer using the call
1264 ptrace(PTRACE_ATTACH, pid, 0, 0);
1269 If the tracer wants this
1271 to have no effect, it needs to suppress it.
1272 Note that if other signals are concurrently sent to
1273 this thread during attach,
1274 the tracer may see the tracee enter signal-delivery-stop
1275 with other signal(s) first!
1276 The usual practice is to reinject these signals until
1278 is seen, then suppress
1281 The design bug here is that a ptrace attach and a concurrently delivered
1283 may race and the concurrent
1287 .\" FIXME: Describe how to attach to a thread which is already
1290 Since attaching sends
1292 and the tracer usually suppresses it, this may cause a stray
1294 return from the currently executing system call in the tracee,
1295 as described in the "signal injection and suppression" section.
1299 ptrace(PTRACE_TRACEME, 0, 0, 0);
1301 turns the calling thread into a tracee.
1302 The thread continues to run (doesn't enter ptrace-stop).
1303 A common practice is to follow the
1309 and allow the parent (which is our tracer now) to observe our
1310 signal-delivery-stop.
1313 .BR PTRACE_O_TRACEFORK ,
1314 .BR PTRACE_O_TRACEVFORK ,
1316 .BR PTRACE_O_TRACECLONE
1317 options are in effect, then children created by, respectively,
1327 with the exit signal set to
1331 are automatically attached to the same tracer which traced their parent.
1333 is delivered to the children, causing them to enter
1334 signal-delivery-stop after they exit the system call which created them.
1336 Detaching of the tracee is performed by:
1338 ptrace(PTRACE_DETACH, pid, 0, sig);
1341 is a restarting operation;
1342 therefore it requires the tracee to be in ptrace-stop.
1343 If the tracee is in signal-delivery-stop, a signal can be injected.
1346 parameter may be silently ignored.
1348 If the tracee is running when the tracer wants to detach it,
1349 the usual solution is to send
1353 to make sure it goes to the correct thread),
1354 wait for the tracee to stop in signal-delivery-stop for
1356 and then detach it (suppressing
1359 A design bug is that this can race with concurrent
1361 Another complication is that the tracee may enter other ptrace-stops
1362 and needs to be restarted and waited for again, until
1365 Yet another complication is to be sure that
1366 the tracee is not already ptrace-stopped,
1367 because no signal delivery happens while it is\(emnot even
1369 .\" FIXME: Describe how to detach from a group-stopped tracee so that it
1370 .\" doesn't run, but continues to wait for SIGCONT.
1372 If the tracer dies, all tracees are automatically detached and restarted,
1373 unless they were in group-stop.
1374 Handling of restart from group-stop is currently buggy,
1375 but the "as planned" behavior is to leave tracee stopped and waiting for
1377 If the tracee is restarted from signal-delivery-stop,
1378 the pending signal is injected.
1379 .SS execve(2) under ptrace
1380 .\" clone(2) THREAD_CLONE says:
1381 .\" If any of the threads in a thread group performs an execve(2),
1382 .\" then all threads other than the thread group leader are terminated,
1383 .\" and the new program is executed in the thread group leader.
1385 When one thread in a multithreaded process calls
1387 the kernel destroys all other threads in the process,
1388 .\" In kernel 3.1 sources, see fs/exec.c::de_thread()
1389 and resets the thread ID of the execing thread to the
1390 thread group ID (process ID).
1391 (Or, to put things another way, when a multithreaded process does an
1393 at completion of the call, it appears as though the
1395 occurred in the thread group leader, regardless of which thread did the
1397 This resetting of the thread ID looks very confusing to tracers:
1399 All other threads stop in
1400 .B PTRACE_EVENT_EXIT
1402 .BR PTRACE_O_TRACEEXIT
1403 option was turned on.
1404 Then all other threads except the thread group leader report
1405 death as if they exited via
1410 .B PTRACE_EVENT_EXEC
1411 stop happens, if the
1412 .BR PTRACE_O_TRACEEXEC
1413 option was turned on.
1415 The execing tracee changes its thread ID while it is in the
1417 (Remember, under ptrace, the "pid" returned from
1419 or fed into ptrace calls, is the tracee's thread ID.)
1420 That is, the tracee's thread ID is reset to be the same as its process ID,
1421 which is the same as the thread group leader's thread ID.
1423 If the thread group leader has reported its death by this time,
1424 it appears to the tracer that
1425 the dead thread leader "reappears from nowhere".
1426 If the thread group leader was still alive,
1427 for the tracer this may look as if thread group leader
1428 returns from a different system call than it entered,
1429 or even "returned from a system call even though
1430 it was not in any system call".
1431 If the thread group leader was not traced
1432 (or was traced by a different tracer), then during
1434 it will appear as if it has become a tracee of
1435 the tracer of the execing tracee.
1437 All of the above effects are the artifacts of
1438 the thread ID change in the tracee.
1441 .B PTRACE_O_TRACEEXEC
1442 option is the recommended tool for dealing with this situation.
1444 .B PTRACE_EVENT_EXEC
1445 stop, which occurs before
1449 .BR PTRACE_EVENT_EXEC -stop,
1453 In this stop, the tracer can use
1454 .B PTRACE_GETEVENTMSG
1455 to retrieve the tracee's former thread ID.
1456 (This feature was introduced in Linux 3.0).
1458 .B PTRACE_O_TRACEEXEC
1459 option disables legacy
1464 When the tracer receives
1465 .B PTRACE_EVENT_EXEC
1467 it is guaranteed that except this tracee and the thread group leader,
1468 no other threads from the process are alive.
1471 .B PTRACE_EVENT_EXEC
1473 the tracer should clean up all its internal
1474 data structures describing the threads of this process,
1475 and retain only one data structure\(emone which
1476 describes the single still running tracee, with
1478 thread ID == thread group ID == process id.
1480 Currently, there is no way to retrieve the former
1481 thread ID of the execing tracee.
1482 If the tracer doesn't keep track of its tracees' thread group relations,
1483 it may be unable to know which tracee execed and therefore no longer
1484 exists under the old thread ID due to a thread ID change.
1486 Example: two threads call
1491 *** we get syscall-entry-stop in thread 1: **
1492 PID1 execve("/bin/foo", "foo" <unfinished ...>
1493 *** we issue PTRACE_SYSCALL for thread 1 **
1494 *** we get syscall-entry-stop in thread 2: **
1495 PID2 execve("/bin/bar", "bar" <unfinished ...>
1496 *** we issue PTRACE_SYSCALL for thread 2 **
1497 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
1498 *** we get syscall-exit-stop for PID0: **
1499 PID0 <... execve resumed> ) = 0
1502 In this situation, there is no way to know which
1507 .B PTRACE_O_TRACEEXEC
1510 in effect for the execing tracee, the kernel delivers an extra
1515 This is an ordinary signal (similar to one which can be
1518 not a special kind of ptrace-stop.
1520 .B PTRACE_GETSIGINFO
1521 for this signal returns
1525 This signal may be blocked by signal mask,
1526 and thus may be delivered (much) later.
1528 Usually, the tracer (for example,
1530 would not want to show this extra post-execve
1532 signal to the user, and would suppress its delivery to the tracee (if
1536 it is a killing signal).
1537 However, determining
1540 to suppress is not easy.
1542 .B PTRACE_O_TRACEEXEC
1543 option and thus suppressing this extra
1545 is the recommended approach.
1547 The ptrace API (ab)uses the standard UNIX parent/child signaling over
1549 This used to cause the real parent of the process to stop receiving
1552 notifications when the child process is traced by some other process.
1554 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
1555 exist; see BUGS below.
1557 As of Linux 2.6.38, the following is believed to work correctly:
1559 exit/death by signal is reported first to the tracer, then,
1560 when the tracer consumes the
1562 result, to the real parent (to the real parent only when the
1563 whole multithreaded process exits).
1564 If the tracer and the real parent are the same process,
1565 the report is sent only once.
1569 requests return the requested data,
1570 while other requests return zero.
1571 On error, all requests return \-1, and
1573 is set appropriately.
1574 Since the value returned by a successful
1576 request may be \-1, the caller must clear
1578 before the call, and then check it afterward
1579 to determine whether or not an error occurred.
1583 (i386 only) There was an error with allocating or freeing a debug register.
1586 There was an attempt to read from or write to an invalid area in
1587 the tracer's or the tracee's memory,
1588 probably because the area wasn't mapped or accessible.
1589 Unfortunately, under Linux, different variations of this fault
1594 more or less arbitrarily.
1597 An attempt was made to set an invalid option.
1601 is invalid, or an attempt was made to read from or
1602 write to an invalid area in the tracer's or the tracee's memory,
1603 or there was a word-alignment violation,
1604 or an invalid signal was specified during a restart request.
1607 The specified process cannot be traced.
1608 This could be because the
1609 tracer has insufficient privileges (the required capability is
1610 .BR CAP_SYS_PTRACE );
1611 unprivileged processes cannot trace processes that they
1612 cannot send signals to or those running
1613 set-user-ID/set-group-ID programs, for obvious reasons.
1614 Alternatively, the process may already be being traced,
1615 or (on kernels before 2.6.26) be
1620 The specified process does not exist, or is not currently being traced
1621 by the caller, or is not stopped
1622 (for requests that require a stopped tracee).
1626 Although arguments to
1628 are interpreted according to the prototype given,
1629 glibc currently declares
1631 as a variadic function with only the
1634 This means that unneeded trailing arguments may be omitted,
1635 though doing so makes use of undocumented
1639 In Linux kernels before 2.6.26,
1640 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
1642 the process with PID 1, may not be traced.
1644 The layout of the contents of memory and the USER area are
1645 quite operating-system- and architecture-specific.
1646 The offset supplied, and the data returned,
1647 might not entirely match with the definition of
1649 .\" See http://lkml.org/lkml/2008/5/8/375
1651 The size of a "word" is determined by the operating-system variant
1652 (e.g., for 32-bit Linux it is 32 bits, etc.).
1654 This page documents the way the
1656 call works currently in Linux.
1657 Its behavior differs noticeably on other flavors of UNIX.
1660 is highly specific to the operating system and architecture.
1662 On hosts with 2.6 kernel headers,
1663 .B PTRACE_SETOPTIONS
1664 is declared with a different value than the one for 2.4.
1665 This leads to applications compiled with 2.6 kernel
1666 headers failing when run on 2.4 kernels.
1667 This can be worked around by redefining
1668 .B PTRACE_SETOPTIONS
1670 .BR PTRACE_OLDSETOPTIONS ,
1673 Group-stop notifications are sent to the tracer, but not to real parent.
1674 Last confirmed on 2.6.38.6.
1676 If a thread group leader is traced and exits by calling
1678 .\" Note from Denys Vlasenko:
1679 .\" Here "exits" means any kind of death - _exit, exit_group,
1680 .\" signal death. Signal death and exit_group cases are trivial,
1681 .\" though: since signal death and exit_group kill all other threads
1682 .\" too, "until all other threads exit" thing happens rather soon
1683 .\" in these cases. Therefore, only _exit presents observably
1684 .\" puzzling behavior to ptrace users: thread leader _exit's,
1685 .\" but WIFEXITED isn't reported! We are trying to explain here
1688 .B PTRACE_EVENT_EXIT
1689 stop will happen for it (if requested), but the subsequent
1691 notification will not be delivered until all other threads exit.
1692 As explained above, if one of other threads calls
1694 the death of the thread group leader will
1697 If the execed thread is not traced by this tracer,
1698 the tracer will never know that
1701 One possible workaround is to
1703 the thread group leader instead of restarting it in this case.
1704 Last confirmed on 2.6.38.6.
1705 .\" FIXME: ^^^ need to test/verify this scenario
1709 signal may still cause a
1710 .B PTRACE_EVENT_EXIT
1711 stop before actual signal death.
1712 This may be changed in the future;
1714 is meant to always immediately kill tasks even under ptrace.
1715 Last confirmed on 2.6.38.6.
1728 .BR capabilities (7),