.\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.)
.\" 2011-09, major update by Denys Vlasenko <vda.linux@googlemail.com>
.\"
-.\" FIXME (later): Linux 3.1 adds PTRACE_SEIZE, PTRACE_INTERRUPT,
+.\" FIXME Linux 2.6.34 adds PTRACE_GETREGSET/PTRACE_SETREGSET
+.\" FIXME Linux 3.1 adds PTRACE_SEIZE, PTRACE_INTERRUPT,
.\" and PTRACE_LISTEN.
.\"
-.TH PTRACE 2 2012-03-06 "Linux" "Linux Programmer's Manual"
+.TH PTRACE 2 2012-03-24 "Linux" "Linux Programmer's Manual"
.SH NAME
ptrace \- process trace
.SH SYNOPSIS
status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8))
.fi
+If the execing thread is not a thread group leader,
+the thread ID is reset to thread group leader's ID before this stop.
+Since Linux 3.0, the former thread ID can be retrieved with
+.BR PTRACE_GETEVENTMSG .
.TP
.BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)"
Stop the tracee at the completion of the next
.I data
argument is treated as for
.BR PTRACE_CONT .
-.RI (addr
+.RI ( addr
is ignored.)
.TP
.BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
of which method was used to initiate tracing.
.RI ( addr
is ignored.)
-.\"
-.\" In the text below, we decided to avoid prettifying the text with markup:
-.\" it would make the source nearly impossible to edit, and we _do_ intend
-.\" to edit it often, in order to keep it updated:
-.\" ptrace API is full of quirks, no need to compound this situation by
-.\" making it excruciatingly painful to document them!
-.\"
.SS Death under ptrace
When a (possibly multithreaded) process receives a killing signal
(one whose disposition is set to
.\" describe how wait notifications queue (or not queue)
.LP
The following kinds of ptrace-stops exist: signal-delivery-stops,
-group-stop, PTRACE_EVENT stops, syscall-stops
-.BR PTRACE_SINGLESTEP ,
-.BR PTRACE_SYSEMU ,
-and
-.BE PTRACE_SYSEMU_SINGLESTEP .
+group-stops,
+.B PTRACE_EVENT
+stops, syscall-stops.
They all are reported by
.BR waitpid (2)
with
.I WSTOPSIG(status)
macro can't be used to perform this examination,
because it returns the value
-(\fIstatus\>>8)\ \fB&\ 0xff\fP\fP.)
+.IR "(status\>>8)\ &\ 0xff" .)
.SS Signal-delivery-stop
When a (possibly multithreaded) process receives any signal except
.BR SIGKILL ,
.BR waitpid (2)
returning with
.I WIFSTOPPED(status)
-true, with the stopping signal returned by
+true, with the signal returned by
.IR WSTOPSIG(status) .
-If the stopping signal is
+If the signal is
.BR SIGTRAP ,
this may be a different kind of ptrace-stop;
see the "Syscall-stops" and "execve" sections below for details.
.LP
Note that a suppressed signal still causes system calls to return
prematurely.
-Restartable system calls will be restarted (the tracer will
-observe the tracee to execute
-.BR restart_syscall(2)
-if the tracer uses
-.BR PTRACE_SYSCALL );
-non-restartable system calls may fail with
+In this case system calls will be restarted: the tracer will
+observe the tracee to reexecute the interrupted system call (or
+.BR restart_syscall (2)
+system call for a few syscalls which use a different mechanism
+for restarting) if the tracer uses
+.BR PTRACE_SYSCALL .
+Even system calls (such as
+.BR poll (2))
+which are not restartable after signal are restarted after
+signal is suppressed;
+however, kernel bugs exist which cause some syscalls to fail with
.B EINTR
even though no observable signal is injected to the tracee.
.LP
signal has a side effect of waking up (all threads of)
a group-stopped process.
This side effect happens before signal-delivery-stop.
-The tracer can't suppress this side-effect (it can
+The tracer can't suppress this side effect (it can
only suppress signal injection, which only causes the
.BR SIGCONT
handler to not be executed in the tracee, if such a handler is installed).
.TP
.B PTRACE_EVENT_CLONE
Stop before return from
-.BR clone (2)
+.BR clone (2).
.TP
.B PTRACE_EVENT_VFORK_DONE
Stop before return from
.B PTRACE_EVENT_EXEC
Stop before return from
.BR execve (2).
+Since Linux 3.0,
+.BR PTRACE_GETEVENTMSG
+returns the former thread ID.
.TP
.B PTRACE_EVENT_EXIT
Stop before exit (including death from
on
.B PTRACE_EVENT
stops returns
-.B SIGTRAP in
+.B SIGTRAP
+in
.IR si_signo ,
with
.I si_code
.LP
Using the
.B PTRACE_O_TRACESYSGOOD
-option is the recommended method to distinquish syscall-stops
+option is the recommended method to distinguish syscall-stops
from other kinds of ptrace-stops,
since it is reliable and does not incur a performance penalty.
.LP
.BR PTRACE_SINGLESTEP ,
.BR PTRACE_SYSEMU ,
or
-.BR PTRACE_SYSEMU_SINGLESTEP.
+.BR PTRACE_SYSEMU_SINGLESTEP .
If the tracee is in signal-delivery-stop,
.I sig
is the signal to be injected (if it is nonzero).
may be ignored.
(When restarting a tracee from a ptrace-stop other than signal-delivery-stop,
recommended practice is to always pass 0 in
-.I sig .)
+.IR sig .)
.SS Attaching and detaching
A thread can be attached to the tracer using the call
Since attaching sends
.B SIGSTOP
and the tracer usually suppresses it, this may cause a stray
-.I EINTR
+.B EINTR
return from the currently executing system call in the tracee,
-as described in the "signal injection and suppression" section.
+as described in the "Signal injection and suppression" section.
.LP
The request
.BR _exit (2)
with exit code 0.
.IP *
-Then a
-.B PTRACE_EVENT_EXEC
-stop happens, if the
-.BR PTRACE_O_TRACEEXEC
-option was turned on.
-.IP *
The execing tracee changes its thread ID while it is in the
.BR execve (2).
(Remember, under ptrace, the "pid" returned from
That is, the tracee's thread ID is reset to be the same as its process ID,
which is the same as the thread group leader's thread ID.
.IP *
-If the thread group leader has reported its death by this time,
+Then a
+.B PTRACE_EVENT_EXEC
+stop happens, if the
+.BR PTRACE_O_TRACEEXEC
+option was turned on.
+.IP *
+If the thread group leader has reported its
+.B PTRACE_EVENT_EXIT
+stop by this time,
it appears to the tracer that
the dead thread leader "reappears from nowhere".
+(Note: the thread group leader does not report death via
+.I WIFEXITED(status)
+until there is at least one other live thread.
+This eliminates the possibility that the tracer will see
+it dying and then reappearing.)
If the thread group leader was still alive,
for the tracer this may look as if thread group leader
returns from a different system call than it entered,
The
.B PTRACE_O_TRACEEXEC
option is the recommended tool for dealing with this situation.
-It enables
-.B PTRACE_EVENT_EXEC
-stop, which occurs before
-.BR execve (2)
-returns.
First, it enables
-.BR PTRACE_EVENT_EXEC -stop,
+.BR PTRACE_EVENT_EXEC
+stop,
which occurs before
-.BR execve(2)
+.BR execve (2)
returns.
In this stop, the tracer can use
.B PTRACE_GETEVENTMSG
and retain only one data structure\(emone which
describes the single still running tracee, with
- thread ID == thread group ID == process id.
-.LP
-Currently, there is no way to retrieve the former
-thread ID of the execing tracee.
-If the tracer doesn't keep track of its tracees' thread group relations,
-it may be unable to know which tracee execed and therefore no longer
-exists under the old thread ID due to a thread ID change.
+ thread ID == thread group ID == process ID.
.LP
Example: two threads call
.BR execve (2)
at the same time:
.LP
.nf
-*** we get syscall-entry-stop in thread 1: **
+*** we get syscall-enter-stop in thread 1: **
PID1 execve("/bin/foo", "foo" <unfinished ...>
*** we issue PTRACE_SYSCALL for thread 1 **
-*** we get syscall-entry-stop in thread 2: **
+*** we get syscall-enter-stop in thread 2: **
PID2 execve("/bin/bar", "bar" <unfinished ...>
*** we issue PTRACE_SYSCALL for thread 2 **
*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **
PID0 <... execve resumed> ) = 0
.fi
.LP
-In this situation, there is no way to know which
-.BR execve (2)
-succeeded.
-.LP
If the
.B PTRACE_O_TRACEEXEC
option is
.B SIGKILL
is meant to always immediately kill tasks even under ptrace.
Last confirmed on 2.6.38.6.
+.LP
+Some system calls return with
+.B EINTR
+if a signal was sent to a tracee, but delivery was suppressed by the tracer.
+(This is very typical operation: it is usually
+done by debuggers on every attach, in order to not introduce
+a bogus
+.BR SIGSTOP ).
+As of Linux 3.2.9, the following system calls are affected
+(this list is likely incomplete):
+.BR epoll_wait (2),
+and
+.BR read (2)
+from an
+.BR inotify (7)
+file descriptor.
.SH "SEE ALSO"
.BR gdb (1),
.BR strace (1),
OSDN Git Service
