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 Linux 2.6.34 adds PTRACE_GETREGSET/PTRACE_SETREGSET
46 .\" FIXME Linux 3.1 adds PTRACE_SEIZE, PTRACE_INTERRUPT,
47 .\" and PTRACE_LISTEN.
49 .TH PTRACE 2 2013-01-27 "Linux" "Linux Programmer's Manual"
51 ptrace \- process trace
54 .B #include <sys/ptrace.h>
56 .BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", "
57 .BI " void *" addr ", void *" data );
62 system call provides a means by which one process (the "tracer")
63 may observe and control the execution of another process (the "tracee"),
64 and examine and change the tracee's memory and registers.
65 It is primarily used to implement breakpoint debugging and system
68 A tracee first needs to be attached to the tracer.
69 Attachment and subsequent commands are per thread:
70 in a multithreaded process,
71 every thread can be individually attached to a
72 (potentially different) tracer,
73 or left not attached and thus not debugged.
74 Therefore, "tracee" always means "(one) thread",
75 never "a (possibly multithreaded) process".
76 Ptrace commands are always sent to
77 a specific tracee using a call of the form
79 ptrace(PTRACE_foo, pid, ...)
83 is the thread ID of the corresponding Linux thread.
85 (Note that in this page, a "multithreaded process"
86 means a thread group consisting of threads created using the
91 A process can initiate a trace by calling
93 and having the resulting child do a
95 followed (typically) by an
97 Alternatively, one process may commence tracing another process using
100 While being traced, the tracee will stop each time a signal is delivered,
101 even if the signal is being ignored.
104 which has its usual effect.)
105 The tracer will be notified at its next call to
107 (or one of the related "wait" system calls); that call will return a
109 value containing information that indicates
110 the cause of the stop in the tracee.
111 While the tracee is stopped,
112 the tracer can use various ptrace requests to inspect and modify the tracee.
113 The tracer then causes the tracee to continue,
114 optionally ignoring the delivered signal
115 (or even delivering a different signal instead).
118 .B PTRACE_O_TRACEEXEC
119 option is not in effect, all successful calls to
121 by the traced process will cause it to be sent a
124 giving the parent a chance to gain control before the new program
127 When the tracer is finished tracing, it can cause the tracee to continue
128 executing in a normal, untraced mode via
133 determines the action to be performed:
136 Indicate that this process is to be traced by its parent.
137 A process probably shouldn't make this request if its parent
138 isn't expecting to trace it.
147 request is used only by the tracee;
148 the remaining requests are used only by the tracer.
149 In the following requests,
151 specifies the thread ID of the tracee to be acted on.
152 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 Copy 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_GETSIGINFO " (since Linux 2.3.99-pre6)"
239 Retrieve information about the signal that caused the stop.
244 from the tracee to the address
250 .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
251 Copy the tracee's general-purpose or floating-point registers,
252 respectively, from the address
256 .BR PTRACE_POKEUSER ,
257 some general-purpose register modifications may be disallowed.
258 .\" FIXME In the preceding sentence, which modifications are disallowed,
259 .\" and when they are disallowed, how does user space discover that fact?
262 Note that SPARC systems have the meaning of
268 is ignored and the registers are copied from the address
273 are not present on all architectures.
275 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
276 Set signal information:
279 structure from the address
281 in the tracer to the tracee.
282 This will affect only signals that would normally be delivered to
283 the tracee and were caught by the tracer.
284 It may be difficult to tell
285 these normal signals from synthetic signals generated by
291 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
292 Set ptrace options from
297 is interpreted as a bit mask of options,
298 which are specified by the following flags:
303 .BR PTRACE_O_EXITKILL " (since Linux 3.8)"
304 .\" commit 992fb6e170639b0849bace8e49bf31bd37c4123
305 If a tracer sets this flag, a
307 signal will be sent to every tracee if the tracer exits.
308 This option is useful for ptrace jailers that
309 want to ensure that tracees can never escape the tracer's control.
312 .BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)"
313 Stop the tracee at the next
315 and automatically start tracing the newly cloned process,
316 which will start with a
320 by the tracer will return a
325 status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8))
328 The PID of the new process can be retrieved with
329 .BR PTRACE_GETEVENTMSG .
331 This option may not catch
339 .B PTRACE_EVENT_VFORK
340 will be delivered instead
342 .B PTRACE_O_TRACEVFORK
343 is set; otherwise if the tracee calls
345 with the exit signal set to
349 .B PTRACE_O_TRACEFORK
353 .BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)"
354 Stop the tracee at the next
358 by the tracer will return a
363 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
366 If the execing thread is not a thread group leader,
367 the thread ID is reset to thread group leader's ID before this stop.
368 Since Linux 3.0, the former thread ID can be retrieved with
369 .BR PTRACE_GETEVENTMSG .
372 .BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)"
373 Stop the tracee at exit.
376 by the tracer will return a
381 status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8))
384 The tracee's exit status can be retrieved with
385 .BR PTRACE_GETEVENTMSG .
387 The tracee is stopped early during process exit,
388 when registers are still available,
389 allowing the tracer to see where the exit occurred,
390 whereas the normal exit notification is done after the process
392 Even though context is available,
393 the tracer cannot prevent the exit from happening at this point.
396 .BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)"
397 Stop the tracee at the next
399 and automatically start tracing the newly forked process,
400 which will start with a
404 by the tracer will return a
409 status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8))
412 The PID of the new process can be retrieved with
413 .BR PTRACE_GETEVENTMSG .
416 .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
417 When delivering system call traps, set bit 7 in the signal number
419 .IR "SIGTRAP|0x80" ).
420 This makes it easy for the tracer to distinguish
421 normal traps from those caused by a system call.
422 .RB ( PTRACE_O_TRACESYSGOOD
423 may not work on all architectures.)
425 .BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)"
426 Stop the tracee at the next
428 and automatically start tracing the newly vforked process,
429 which will start with a
433 by the tracer will return a
438 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8))
441 The PID of the new process can be retrieved with
442 .BR PTRACE_GETEVENTMSG .
444 .BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
445 Stop the tracee at the completion of the next
449 by the tracer will return a
454 status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8))
457 The PID of the new process can (since Linux 2.6.18) be retrieved with
458 .BR PTRACE_GETEVENTMSG .
463 .BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)"
464 Retrieve a message (as an
465 .IR "unsigned long" )
466 about the ptrace event
467 that just happened, placing it at the address
471 .BR PTRACE_EVENT_EXIT ,
472 this is the tracee's exit status.
474 .BR PTRACE_EVENT_FORK ,
475 .BR PTRACE_EVENT_VFORK ,
476 .BR PTRACE_EVENT_VFORK_DONE ,
478 .BR PTRACE_EVENT_CLONE ,
479 this is the PID of the new process.
484 Restart the stopped tracee process.
488 it is interpreted as the number of a signal to be delivered to the tracee;
489 otherwise, no signal is delivered.
490 Thus, for example, the tracer can control
491 whether a signal sent to the tracee is delivered or not.
495 .BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP
496 Restart the stopped tracee as for
498 but arrange for the tracee to be stopped at
499 the next entry to or exit from a system call,
500 or after execution of a single instruction, respectively.
501 (The tracee will also, as usual, be stopped upon receipt of a signal.)
502 From the tracer's perspective, the tracee will appear to have been
503 stopped by receipt of a
507 for example, the idea is to inspect
508 the arguments to the system call at the first stop,
511 and inspect the return value of the system call at the second stop.
514 argument is treated as for
519 .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
522 continue and stop on entry to the next system call,
523 which will not be executed.
525 .BR PTRACE_SYSEMU_SINGLESTEP ,
526 do the same but also singlestep if not a system call.
527 This call is used by programs like
528 User Mode Linux that want to emulate all the tracee's system calls.
531 argument is treated as for
536 These requests are currently
538 supported only on x86.
549 .I This operation is deprecated; do not use it!
558 is that it requires the tracee to be in signal-delivery-stop,
559 otherwise it may not work
560 (i.e., may complete successfully but won't kill the tracee).
561 By contrast, sending a
563 directly has no such limitation.
564 .\" [Note from Denys Vlasenko:
565 .\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it
566 .\" instead of describing (and needing to support) PTRACE_KILL's quirks.]
569 Attach to the process specified in
571 making it a tracee of the calling process.
572 .\" No longer true (removed by Denys Vlasenko, 2011, who remarks:
573 .\" "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
574 .\" Basically, it's not true for any Linux in practical use.
575 .\" ; the behavior of the tracee is as if it had done a
576 .\" .BR PTRACE_TRACEME .
577 .\" The calling process actually becomes the parent of the tracee
578 .\" process for most purposes (e.g., it will receive
579 .\" notification of tracee events and appears in
581 .\" output as the tracee's parent), but a
583 .\" by the tracee will still return the PID of the original parent.
586 but will not necessarily have stopped
587 by the completion of this call; use
589 to wait for the tracee to stop.
590 See the "Attaching and detaching" subsection for additional information.
597 Restart the stopped tracee as for
599 but first detach from it.
600 Under Linux, a tracee can be detached in this way regardless
601 of which method was used to initiate tracing.
604 .SS Death under ptrace
605 When a (possibly multithreaded) process receives a killing signal
606 (one whose disposition is set to
608 and whose default action is to kill the process),
610 Tracees report their death to their tracer(s).
611 Notification of this event is delivered via
614 Note that the killing signal will first cause signal-delivery-stop
615 (on one tracee only),
616 and only after it is injected by the tracer
617 (or after it was dispatched to a thread which isn't traced),
618 will death from the signal happen on
620 tracees within a multithreaded process.
621 (The term "signal-delivery-stop" is explained below.)
624 does not generate signal-delivery-stop and
625 therefore the tracer can't suppress it.
627 kills even within system calls
628 (syscall-exit-stop is not generated prior to death by
630 The net effect is that
632 always kills the process (all its threads),
633 even if some threads of the process are ptraced.
635 When the tracee calls
637 it reports its death to its tracer.
638 Other threads are not affected.
640 When any thread executes
642 every tracee in its thread group reports its death to its tracer.
645 .B PTRACE_O_TRACEEXIT
648 will happen before actual death.
649 This applies to exits via
652 and signal deaths (except
654 and when threads are torn down on
656 in a multithreaded process.
658 The tracer cannot assume that the ptrace-stopped tracee exists.
659 There are many scenarios when the tracee may die while stopped (such as
661 Therefore, the tracer must be prepared to handle an
663 error on any ptrace operation.
664 Unfortunately, the same error is returned if the tracee
665 exists but is not ptrace-stopped
666 (for commands which require a stopped tracee),
667 or if it is not traced by the process which issued the ptrace call.
668 The tracer needs to keep track of the stopped/running state of the tracee,
671 as "tracee died unexpectedly" only if it knows that the tracee has
672 been observed to enter ptrace-stop.
673 Note that there is no guarantee that
675 will reliably report the tracee's death status if a
676 ptrace operation returned
679 may return 0 instead.
680 In other words, the tracee may be "not yet fully dead",
681 but already refusing ptrace requests.
683 The tracer can't assume that the tracee
685 ends its life by reporting
688 .IR WIFSIGNALED(status) ;
689 there are cases where this does not occur.
690 For example, if a thread other than thread group leader does an
693 its PID will never be seen again,
694 and any subsequent ptrace stops will be reported under
695 the thread group leader's PID.
697 A tracee can be in two states: running or stopped.
699 There are many kinds of states when the tracee is stopped, and in ptrace
700 discussions they are often conflated.
701 Therefore, it is important to use precise terms.
703 In this manual page, any stopped state in which the tracee is ready
704 to accept ptrace commands from the tracer is called
707 be further subdivided into
708 .IR signal-delivery-stop ,
712 These stopped states are described in detail below.
714 When the running tracee enters ptrace-stop, it notifies its tracer using
716 (or one of the other "wait" system calls).
717 Most of this manual page assumes that the tracer waits with:
719 pid = waitpid(pid_or_minus_1, &status, __WALL);
721 Ptrace-stopped tracees are reported as returns with
724 .I WIFSTOPPED(status)
727 .\" Do we require __WALL usage, or will just using 0 be ok? (With 0,
728 .\" I am not 100% sure there aren't ugly corner cases.) Are the
729 .\" rules different if user wants to use waitid? Will waitid require
735 flag does not include the
739 flags, but implies their functionality.
745 is not recommended: the "continued" state is per-process and
746 consuming it can confuse the real parent of the tracee.
752 to return 0 ("no wait results available yet")
753 even if the tracer knows there should be a notification.
758 ptrace(PTRACE_CONT, pid, 0L, 0L);
759 if (errno == ESRCH) {
761 r = waitpid(tracee, &status, __WALL | WNOHANG);
762 /* r can still be 0 here! */
766 .\" waitid usage? WNOWAIT?
767 .\" describe how wait notifications queue (or not queue)
769 The following kinds of ptrace-stops exist: signal-delivery-stops,
772 stops, syscall-stops.
773 They all are reported by
776 .I WIFSTOPPED(status)
778 They may be differentiated by examining the value
780 and if there is ambiguity in that value, by querying
781 .BR PTRACE_GETSIGINFO .
784 macro can't be used to perform this examination,
785 because it returns the value
786 .IR "(status>>8)\ &\ 0xff" .)
787 .SS Signal-delivery-stop
788 When a (possibly multithreaded) process receives any signal except
790 the kernel selects an arbitrary thread which handles the signal.
791 (If the signal is generated with
793 the target thread can be explicitly selected by the caller.)
794 If the selected thread is traced, it enters signal-delivery-stop.
795 At this point, the signal is not yet delivered to the process,
796 and can be suppressed by the tracer.
797 If the tracer doesn't suppress the signal,
798 it passes the signal to the tracee in the next ptrace restart request.
799 This second step of signal delivery is called
800 .I "signal injection"
802 Note that if the signal is blocked,
803 signal-delivery-stop doesn't happen until the signal is unblocked,
804 with the usual exception that
808 Signal-delivery-stop is observed by the tracer as
811 .I WIFSTOPPED(status)
812 true, with the signal returned by
813 .IR WSTOPSIG(status) .
816 this may be a different kind of ptrace-stop;
817 see the "Syscall-stops" and "execve" sections below for details.
820 returns a stopping signal, this may be a group-stop; see below.
821 .SS Signal injection and suppression
822 After signal-delivery-stop is observed by the tracer,
823 the tracer should restart the tracee with the call
825 ptrace(PTRACE_restart, pid, 0, sig)
829 is one of the restarting ptrace requests.
832 is 0, then a signal is not delivered.
833 Otherwise, the signal
836 This operation is called
837 .I "signal injection"
838 in this manual page, to distinguish it from signal-delivery-stop.
842 value may be different from the
844 value: the tracer can cause a different signal to be injected.
846 Note that a suppressed signal still causes system calls to return
848 In this case system calls will be restarted: the tracer will
849 observe the tracee to reexecute the interrupted system call (or
850 .BR restart_syscall (2)
851 system call for a few syscalls which use a different mechanism
852 for restarting) if the tracer uses
854 Even system calls (such as
856 which are not restartable after signal are restarted after
857 signal is suppressed;
858 however, kernel bugs exist which cause some syscalls to fail with
860 even though no observable signal is injected to the tracee.
862 Restarting ptrace commands issued in ptrace-stops other than
863 signal-delivery-stop are not guaranteed to inject a signal, even if
866 No error is reported; a nonzero
868 may simply be ignored.
869 Ptrace users should not try to "create a new signal" this way: use
873 The fact that signal injection requests may be ignored
874 when restarting the tracee after
875 ptrace stops that are not signal-delivery-stops
876 is a cause of confusion among ptrace users.
877 One typical scenario is that the tracer observes group-stop,
878 mistakes it for signal-delivery-stop, restarts the tracee with
880 ptrace(PTRACE_rest, pid, 0, stopsig)
882 with the intention of injecting
886 gets ignored and the tracee continues to run.
890 signal has a side effect of waking up (all threads of)
891 a group-stopped process.
892 This side effect happens before signal-delivery-stop.
893 The tracer can't suppress this side effect (it can
894 only suppress signal injection, which only causes the
896 handler to not be executed in the tracee, if such a handler is installed).
897 In fact, waking up from group-stop may be followed by
898 signal-delivery-stop for signal(s)
901 if they were pending when
906 may be not the first signal observed by the tracee after it was sent.
908 Stopping signals cause (all threads of) a process to enter group-stop.
909 This side effect happens after signal injection, and therefore can be
910 suppressed by the tracer.
912 In Linux 2.4 and earlier, the
914 signal can't be injected.
915 .\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
918 .\" /* The debugger continued. Ignore SIGSTOP. */
919 .\" if (signr == SIGSTOP)
923 can be used to retrieve a
925 structure which corresponds to the delivered signal.
927 may be used to modify it.
930 has been used to alter
936 parameter in the restarting command must match,
937 otherwise the result is undefined.
939 When a (possibly multithreaded) process receives a stopping signal,
941 If some threads are traced, they enter a group-stop.
942 Note that the stopping signal will first cause signal-delivery-stop
943 (on one tracee only), and only after it is injected by the tracer
944 (or after it was dispatched to a thread which isn't traced),
945 will group-stop be initiated on
947 tracees within the multithreaded process.
948 As usual, every tracee reports its group-stop separately
949 to the corresponding tracer.
951 Group-stop is observed by the tracer as
954 .I WIFSTOPPED(status)
955 true, with the stopping signal available via
956 .IR WSTOPSIG(status) .
957 The same result is returned by some other classes of ptrace-stops,
958 therefore the recommended practice is to perform the call
960 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
962 The call can be avoided if the signal is not
968 only these four signals are stopping signals.
969 If the tracer sees something else, it can't be a group-stop.
970 Otherwise, the tracer needs to call
971 .BR PTRACE_GETSIGINFO .
976 then it is definitely a group-stop.
977 (Other failure codes are possible, such as
979 ("no such process") if a
984 after the tracer sees the tracee ptrace-stop and until it
985 restarts or kills it, the tracee will not run,
986 and will not send notifications (except
988 death) to the tracer, even if the tracer enters into another
992 The kernel behavior described in the previous paragraph
993 causes a problem with transparent handling of stopping signals.
994 If the tracer restarts the tracee after group-stop,
996 is effectively ignored\(emthe tracee doesn't remain stopped, it runs.
997 If the tracer doesn't restart the tracee before entering into the next
1001 signals will not be reported to the tracer;
1002 this would cause the
1004 signals to have no effect on the tracee.
1005 .SS PTRACE_EVENT stops
1008 options, the tracee will enter ptrace-stops called
1013 stops are observed by the tracer as
1016 .IR WIFSTOPPED(status) ,
1021 An additional bit is set in the higher byte of the status word:
1026 (SIGTRAP | PTRACE_EVENT_foo << 8).
1028 The following events exist:
1030 .B PTRACE_EVENT_VFORK
1031 Stop before return from
1038 When the tracee is continued after this stop, it will wait for child to
1039 exit/exec before continuing its execution
1040 (in other words, the usual behavior on
1043 .B PTRACE_EVENT_FORK
1044 Stop before return from
1048 with the exit signal set to
1051 .B PTRACE_EVENT_CLONE
1052 Stop before return from
1055 .B PTRACE_EVENT_VFORK_DONE
1056 Stop before return from
1063 but after the child unblocked this tracee by exiting or execing.
1065 For all four stops described above,
1066 the stop occurs in the parent (i.e., the tracee),
1067 not in the newly created thread.
1068 .BR PTRACE_GETEVENTMSG
1069 can be used to retrieve the new thread's ID.
1071 .B PTRACE_EVENT_EXEC
1072 Stop before return from
1075 .BR PTRACE_GETEVENTMSG
1076 returns the former thread ID.
1078 .B PTRACE_EVENT_EXIT
1079 Stop before exit (including death from
1080 .BR exit_group (2)),
1081 signal death, or exit caused by
1083 in a multithreaded process.
1084 .B PTRACE_GETEVENTMSG
1085 returns the exit status.
1086 Registers can be examined
1087 (unlike when "real" exit happens).
1088 The tracee is still alive; it needs to be
1091 .BR PTRACE_DETACH ed
1094 .B PTRACE_GETSIGINFO
1104 .IR "(event<<8)\ |\ SIGTRAP" .
1106 If the tracee was restarted by
1107 .BR PTRACE_SYSCALL ,
1109 syscall-enter-stop just prior to entering any system call.
1110 If the tracer restarts the tracee with
1111 .BR PTRACE_SYSCALL ,
1112 the tracee enters syscall-exit-stop when the system call is finished,
1113 or if it is interrupted by a signal.
1114 (That is, signal-delivery-stop never happens between syscall-enter-stop
1115 and syscall-exit-stop; it happens
1119 Other possibilities are that the tracee may stop in a
1121 stop, exit (if it entered
1124 .BR exit_group (2)),
1127 or die silently (if it is a thread group leader, the
1129 happened in another thread,
1130 and that thread is not traced by the same tracer;
1131 this situation is discussed later).
1133 Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
1136 .I WIFSTOPPED(status)
1142 .B PTRACE_O_TRACESYSGOOD
1143 option was set by the tracer, then
1146 .IR "(SIGTRAP\ |\ 0x80)" .
1148 Syscall-stops can be distinguished from signal-delivery-stop with
1151 .BR PTRACE_GETSIGINFO
1152 for the following cases:
1156 was delivered as a result of a user-space action,
1157 for example, a system call
1162 expiration of a POSIX timer,
1163 change of state on a POSIX message queue,
1164 or completion of an asynchronous I/O request.
1166 .IR si_code " == SI_KERNEL (0x80)"
1168 was sent by the kernel.
1170 .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
1171 This is a syscall-stop.
1173 However, syscall-stops happen very often (twice per system call),
1175 .B PTRACE_GETSIGINFO
1176 for every syscall-stop may be somewhat expensive.
1178 Some architectures allow the cases to be distinguished
1179 by examining registers.
1180 For example, on x86,
1184 in syscall-enter-stop.
1187 (like any other signal) always happens
1192 almost never contains
1196 looks like "syscall-stop which is not syscall-enter-stop";
1197 in other words, it looks like a
1198 "stray syscall-exit-stop" and can be detected this way.
1199 But such detection is fragile and is best avoided.
1202 .B PTRACE_O_TRACESYSGOOD
1203 option is the recommended method to distinguish syscall-stops
1204 from other kinds of ptrace-stops,
1205 since it is reliable and does not incur a performance penalty.
1207 Syscall-enter-stop and syscall-exit-stop are
1208 indistinguishable from each other by the tracer.
1209 The tracer needs to keep track of the sequence of
1210 ptrace-stops in order to not misinterpret syscall-enter-stop as
1211 syscall-exit-stop or vice versa.
1212 The rule is that syscall-enter-stop is
1213 always followed by syscall-exit-stop,
1215 stop or the tracee's death;
1216 no other kinds of ptrace-stop can occur in between.
1218 If after syscall-enter-stop,
1219 the tracer uses a restarting command other than
1220 .BR PTRACE_SYSCALL ,
1221 syscall-exit-stop is not generated.
1223 .B PTRACE_GETSIGINFO
1224 on syscall-stops returns
1233 .IR (SIGTRAP|0x80) .
1234 .SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops
1235 [Details of these kinds of stops are yet to be documented.]
1238 .\" document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
1239 .\" PTRACE_SYSEMU_SINGLESTEP
1240 .SS Informational and restarting ptrace commands
1241 Most ptrace commands (all except
1243 .BR PTRACE_TRACEME ,
1246 require the tracee to be in a ptrace-stop, otherwise they fail with
1249 When the tracee is in ptrace-stop,
1250 the tracer can read and write data to
1251 the tracee using informational commands.
1252 These commands leave the tracee in ptrace-stopped state:
1255 ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
1256 ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);
1257 ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);
1258 ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);
1259 ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);
1260 ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);
1261 ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);
1262 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1265 Note that some errors are not reported.
1266 For example, setting signal information
1268 may have no effect in some ptrace-stops, yet the call may succeed
1269 (return 0 and not set
1272 .B PTRACE_GETEVENTMSG
1273 may succeed and return some random value if current ptrace-stop
1274 is not documented as returning a meaningful event message.
1278 ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
1281 The tracee's current flags are replaced.
1282 Flags are inherited by new tracees created and "auto-attached" via active
1283 .BR PTRACE_O_TRACEFORK ,
1284 .BR PTRACE_O_TRACEVFORK ,
1286 .BR PTRACE_O_TRACECLONE
1289 Another group of commands makes the ptrace-stopped tracee run.
1292 ptrace(cmd, pid, 0, sig);
1299 .BR PTRACE_SYSCALL ,
1300 .BR PTRACE_SINGLESTEP ,
1303 .BR PTRACE_SYSEMU_SINGLESTEP .
1304 If the tracee is in signal-delivery-stop,
1306 is the signal to be injected (if it is nonzero).
1310 (When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
1311 recommended practice is to always pass 0 in
1313 .SS Attaching and detaching
1314 A thread can be attached to the tracer using the call
1316 ptrace(PTRACE_ATTACH, pid, 0, 0);
1321 If the tracer wants this
1323 to have no effect, it needs to suppress it.
1324 Note that if other signals are concurrently sent to
1325 this thread during attach,
1326 the tracer may see the tracee enter signal-delivery-stop
1327 with other signal(s) first!
1328 The usual practice is to reinject these signals until
1330 is seen, then suppress
1333 The design bug here is that a ptrace attach and a concurrently delivered
1335 may race and the concurrent
1339 .\" FIXME: Describe how to attach to a thread which is already
1342 Since attaching sends
1344 and the tracer usually suppresses it, this may cause a stray
1346 return from the currently executing system call in the tracee,
1347 as described in the "Signal injection and suppression" section.
1351 ptrace(PTRACE_TRACEME, 0, 0, 0);
1353 turns the calling thread into a tracee.
1354 The thread continues to run (doesn't enter ptrace-stop).
1355 A common practice is to follow the
1361 and allow the parent (which is our tracer now) to observe our
1362 signal-delivery-stop.
1365 .BR PTRACE_O_TRACEFORK ,
1366 .BR PTRACE_O_TRACEVFORK ,
1368 .BR PTRACE_O_TRACECLONE
1369 options are in effect, then children created by, respectively,
1379 with the exit signal set to
1383 are automatically attached to the same tracer which traced their parent.
1385 is delivered to the children, causing them to enter
1386 signal-delivery-stop after they exit the system call which created them.
1388 Detaching of the tracee is performed by:
1390 ptrace(PTRACE_DETACH, pid, 0, sig);
1393 is a restarting operation;
1394 therefore it requires the tracee to be in ptrace-stop.
1395 If the tracee is in signal-delivery-stop, a signal can be injected.
1398 parameter may be silently ignored.
1400 If the tracee is running when the tracer wants to detach it,
1401 the usual solution is to send
1405 to make sure it goes to the correct thread),
1406 wait for the tracee to stop in signal-delivery-stop for
1408 and then detach it (suppressing
1411 A design bug is that this can race with concurrent
1413 Another complication is that the tracee may enter other ptrace-stops
1414 and needs to be restarted and waited for again, until
1417 Yet another complication is to be sure that
1418 the tracee is not already ptrace-stopped,
1419 because no signal delivery happens while it is\(emnot even
1421 .\" FIXME: Describe how to detach from a group-stopped tracee so that it
1422 .\" doesn't run, but continues to wait for SIGCONT.
1424 If the tracer dies, all tracees are automatically detached and restarted,
1425 unless they were in group-stop.
1426 Handling of restart from group-stop is currently buggy,
1427 but the "as planned" behavior is to leave tracee stopped and waiting for
1429 If the tracee is restarted from signal-delivery-stop,
1430 the pending signal is injected.
1431 .SS execve(2) under ptrace
1432 .\" clone(2) CLONE_THREAD says:
1433 .\" If any of the threads in a thread group performs an execve(2),
1434 .\" then all threads other than the thread group leader are terminated,
1435 .\" and the new program is executed in the thread group leader.
1437 When one thread in a multithreaded process calls
1439 the kernel destroys all other threads in the process,
1440 .\" In kernel 3.1 sources, see fs/exec.c::de_thread()
1441 and resets the thread ID of the execing thread to the
1442 thread group ID (process ID).
1443 (Or, to put things another way, when a multithreaded process does an
1445 at completion of the call, it appears as though the
1447 occurred in the thread group leader, regardless of which thread did the
1449 This resetting of the thread ID looks very confusing to tracers:
1451 All other threads stop in
1452 .B PTRACE_EVENT_EXIT
1454 .BR PTRACE_O_TRACEEXIT
1455 option was turned on.
1456 Then all other threads except the thread group leader report
1457 death as if they exited via
1461 The execing tracee changes its thread ID while it is in the
1463 (Remember, under ptrace, the "pid" returned from
1465 or fed into ptrace calls, is the tracee's thread ID.)
1466 That is, the tracee's thread ID is reset to be the same as its process ID,
1467 which is the same as the thread group leader's thread ID.
1470 .B PTRACE_EVENT_EXEC
1471 stop happens, if the
1472 .BR PTRACE_O_TRACEEXEC
1473 option was turned on.
1475 If the thread group leader has reported its
1476 .B PTRACE_EVENT_EXIT
1478 it appears to the tracer that
1479 the dead thread leader "reappears from nowhere".
1480 (Note: the thread group leader does not report death via
1481 .I WIFEXITED(status)
1482 until there is at least one other live thread.
1483 This eliminates the possibility that the tracer will see
1484 it dying and then reappearing.)
1485 If the thread group leader was still alive,
1486 for the tracer this may look as if thread group leader
1487 returns from a different system call than it entered,
1488 or even "returned from a system call even though
1489 it was not in any system call".
1490 If the thread group leader was not traced
1491 (or was traced by a different tracer), then during
1493 it will appear as if it has become a tracee of
1494 the tracer of the execing tracee.
1496 All of the above effects are the artifacts of
1497 the thread ID change in the tracee.
1500 .B PTRACE_O_TRACEEXEC
1501 option is the recommended tool for dealing with this situation.
1503 .BR PTRACE_EVENT_EXEC
1508 In this stop, the tracer can use
1509 .B PTRACE_GETEVENTMSG
1510 to retrieve the tracee's former thread ID.
1511 (This feature was introduced in Linux 3.0).
1513 .B PTRACE_O_TRACEEXEC
1514 option disables legacy
1519 When the tracer receives
1520 .B PTRACE_EVENT_EXEC
1522 it is guaranteed that except this tracee and the thread group leader,
1523 no other threads from the process are alive.
1526 .B PTRACE_EVENT_EXEC
1528 the tracer should clean up all its internal
1529 data structures describing the threads of this process,
1530 and retain only one data structure\(emone which
1531 describes the single still running tracee, with
1533 thread ID == thread group ID == process ID.
1535 Example: two threads call
1540 *** we get syscall-enter-stop in thread 1: **
1541 PID1 execve("/bin/foo", "foo" <unfinished ...>
1542 *** we issue PTRACE_SYSCALL for thread 1 **
1543 *** we get syscall-enter-stop in thread 2: **
1544 PID2 execve("/bin/bar", "bar" <unfinished ...>
1545 *** we issue PTRACE_SYSCALL for thread 2 **
1546 *** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
1547 *** we get syscall-exit-stop for PID0: **
1548 PID0 <... execve resumed> ) = 0
1552 .B PTRACE_O_TRACEEXEC
1555 in effect for the execing tracee, the kernel delivers an extra
1560 This is an ordinary signal (similar to one which can be
1563 not a special kind of ptrace-stop.
1565 .B PTRACE_GETSIGINFO
1566 for this signal returns
1570 This signal may be blocked by signal mask,
1571 and thus may be delivered (much) later.
1573 Usually, the tracer (for example,
1575 would not want to show this extra post-execve
1577 signal to the user, and would suppress its delivery to the tracee (if
1581 it is a killing signal).
1582 However, determining
1585 to suppress is not easy.
1587 .B PTRACE_O_TRACEEXEC
1588 option and thus suppressing this extra
1590 is the recommended approach.
1592 The ptrace API (ab)uses the standard UNIX parent/child signaling over
1594 This used to cause the real parent of the process to stop receiving
1597 notifications when the child process is traced by some other process.
1599 Many of these bugs have been fixed, but as of Linux 2.6.38 several still
1600 exist; see BUGS below.
1602 As of Linux 2.6.38, the following is believed to work correctly:
1604 exit/death by signal is reported first to the tracer, then,
1605 when the tracer consumes the
1607 result, to the real parent (to the real parent only when the
1608 whole multithreaded process exits).
1609 If the tracer and the real parent are the same process,
1610 the report is sent only once.
1614 requests return the requested data,
1615 while other requests return zero.
1616 On error, all requests return \-1, and
1618 is set appropriately.
1619 Since the value returned by a successful
1621 request may be \-1, the caller must clear
1623 before the call, and then check it afterward
1624 to determine whether or not an error occurred.
1628 (i386 only) There was an error with allocating or freeing a debug register.
1631 There was an attempt to read from or write to an invalid area in
1632 the tracer's or the tracee's memory,
1633 probably because the area wasn't mapped or accessible.
1634 Unfortunately, under Linux, different variations of this fault
1639 more or less arbitrarily.
1642 An attempt was made to set an invalid option.
1646 is invalid, or an attempt was made to read from or
1647 write to an invalid area in the tracer's or the tracee's memory,
1648 or there was a word-alignment violation,
1649 or an invalid signal was specified during a restart request.
1652 The specified process cannot be traced.
1653 This could be because the
1654 tracer has insufficient privileges (the required capability is
1655 .BR CAP_SYS_PTRACE );
1656 unprivileged processes cannot trace processes that they
1657 cannot send signals to or those running
1658 set-user-ID/set-group-ID programs, for obvious reasons.
1659 Alternatively, the process may already be being traced,
1660 or (on kernels before 2.6.26) be
1665 The specified process does not exist, or is not currently being traced
1666 by the caller, or is not stopped
1667 (for requests that require a stopped tracee).
1671 Although arguments to
1673 are interpreted according to the prototype given,
1674 glibc currently declares
1676 as a variadic function with only the
1679 It is recommended to always supply four arguments,
1680 even if the requested operation does not use them,
1681 setting unused/ignored arguments to
1686 In Linux kernels before 2.6.26,
1687 .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
1689 the process with PID 1, may not be traced.
1691 The layout of the contents of memory and the USER area are
1692 quite operating-system- and architecture-specific.
1693 The offset supplied, and the data returned,
1694 might not entirely match with the definition of
1696 .\" See http://lkml.org/lkml/2008/5/8/375
1698 The size of a "word" is determined by the operating-system variant
1699 (e.g., for 32-bit Linux it is 32 bits).
1701 This page documents the way the
1703 call works currently in Linux.
1704 Its behavior differs noticeably on other flavors of UNIX.
1707 is highly specific to the operating system and architecture.
1709 On hosts with 2.6 kernel headers,
1710 .B PTRACE_SETOPTIONS
1711 is declared with a different value than the one for 2.4.
1712 This leads to applications compiled with 2.6 kernel
1713 headers failing when run on 2.4 kernels.
1714 This can be worked around by redefining
1715 .B PTRACE_SETOPTIONS
1717 .BR PTRACE_OLDSETOPTIONS ,
1720 Group-stop notifications are sent to the tracer, but not to real parent.
1721 Last confirmed on 2.6.38.6.
1723 If a thread group leader is traced and exits by calling
1725 .\" Note from Denys Vlasenko:
1726 .\" Here "exits" means any kind of death - _exit, exit_group,
1727 .\" signal death. Signal death and exit_group cases are trivial,
1728 .\" though: since signal death and exit_group kill all other threads
1729 .\" too, "until all other threads exit" thing happens rather soon
1730 .\" in these cases. Therefore, only _exit presents observably
1731 .\" puzzling behavior to ptrace users: thread leader _exit's,
1732 .\" but WIFEXITED isn't reported! We are trying to explain here
1735 .B PTRACE_EVENT_EXIT
1736 stop will happen for it (if requested), but the subsequent
1738 notification will not be delivered until all other threads exit.
1739 As explained above, if one of other threads calls
1741 the death of the thread group leader will
1744 If the execed thread is not traced by this tracer,
1745 the tracer will never know that
1748 One possible workaround is to
1750 the thread group leader instead of restarting it in this case.
1751 Last confirmed on 2.6.38.6.
1752 .\" FIXME: ^^^ need to test/verify this scenario
1756 signal may still cause a
1757 .B PTRACE_EVENT_EXIT
1758 stop before actual signal death.
1759 This may be changed in the future;
1761 is meant to always immediately kill tasks even under ptrace.
1762 Last confirmed on 2.6.38.6.
1764 Some system calls return with
1766 if a signal was sent to a tracee, but delivery was suppressed by the tracer.
1767 (This is very typical operation: it is usually
1768 done by debuggers on every attach, in order to not introduce
1771 As of Linux 3.2.9, the following system calls are affected
1772 (this list is likely incomplete):
1779 The usual symptom of this bug is that when you attach to
1780 a quiescent process with the command
1782 strace -p <process-ID>
1784 then, instead of the usual
1785 and expected one-line output such as
1788 restart_syscall(<... resuming interrupted call ...>_
1794 select(6, [5], NULL, [5], NULL_
1797 ('_' denotes the cursor position), you observe more than one line.
1801 clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
1805 What is not visible here is that the process was blocked in
1812 to return to user space with the error
1814 In this particular case, the program reacted to
1816 by checking the current time, and then executing
1819 (Programs which do not expect such "stray"
1821 errors may behave in an unintended way upon an
1836 .BR capabilities (7),