[PATCH] ptrace.2: Clarify PTRACE_INTERRUPT, PTRACE_LISTEN and group-stop behavior

[PATCH] ptrace.2: Clarify PTRACE_INTERRUPT, PTRACE_LISTEN and group-stop behavior

[Denys Vlasenko]

From: root <root-bi+AKbBUZKY6gyzm1THtWbp2dZbC/Bob@public.gmane.org>

For easier review, here are the changes as plain text:


PTRACE_INTERRUPT (since Linux 3.4)
Stop a tracee.
[*MODIFIED TEXT->**] If the tracee is running in kernel space
and PTRACE_SYSCALL is in effect, it will stop with syscall-exit-stop.
If the tracee was already stopped by a signal and PTRACE_LISTEN was sent
to it, it will stop with PTRACE_EVENT_STOP with WSTOPSIG(status) ==
stop_sig. If any other ptrace-stop is generated at the same time
(for example, if a signal is sent to the tracee), this ptrace-stop
happens.  If none of the above applies (for example, if the tracee
is running in userspace), it will stop with PTRACE_EVENT_STOP with
WSTOPSIG(status) == SIGTRAP.


Stopped states
A tracee can be in two states: running or stopped.
[**ADDED TEXT->**] For the purposes of ptrace, tracee which is blocked in a syscall
(such as read(2), pause(2) etc) is nevertheless considered to be running,
even if tracee is blocked for a long time.  The state of the tracee after
PTRACE_LISTEN is somewhat of a gray area: it is not in any ptrace-stop
(ptrace commands won't work on it, and it will deliver waitpid
notifications), but it also may be considered "stopped" because it is
not executing instructions (is not scheduled), and if it was in
group-stop before PTRACE_LISTEN, it will not respond to signals until
SIGCONT is received.


Group-stop
...
[**NEW PARAGRAPH ADDED->**]
If tracee was attached using PTRACE_SEIZE, group-stop is indicated
by PTRACE_EVENT_STOP: status>>16 == PTRACE_EVENT_STOP. This allows detection
of group-stops without extra PTRACE_GETSIGINFO call.


PTRACE_EVENT_STOP
Stop induced by PTRACE_INTERRUPT command [**ADDED TEXT->**], or group-stop (only
if attached using PTRACE_SEIZE).


Signed-off-by: Denys Vlasenko <dvlasenk-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
CC: Jan Kratochvil <jan.kratochvil-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
CC: Dmitry V. Levin <ldv-u2l5PoMzF/Vg9hUCZPvPmw@public.gmane.org>
CC: Oleg Nesterov <oleg-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
CC: Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
CC: linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org

---
 man2/ptrace.2 | 46 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 37 insertions(+), 9 deletions(-)

diff --git a/man2/ptrace.2 b/man2/ptrace.2
index 0d77e3f..472ae72 100644
--- a/man2/ptrace.2
+++ b/man2/ptrace.2
@@ -598,14 +598,18 @@ directly has no such limitation.
 .TP
 .BR PTRACE_INTERRUPT " (since Linux 3.4)"
 Stop a tracee.
-If the tracee is running, it will stop with
-.BR PTRACE_EVENT_STOP .
-If the tracee is already stopped by a signal, or receives a signal
-in parallel with
-.BR PTRACE_INTERRUPT ,
-it may report a group-stop
-or a signal-delivery-stop instead of
-.BR PTRACE_EVENT_STOP .
+If the tracee is running in kernel space and PTRACE_SYSCALL is in effect,
+it will stop with syscall-exit-stop.
+If the tracee was already stopped by a signal and PTRACE_LISTEN was sent to it,
+it will stop with
+.B PTRACE_EVENT_STOP
+with WSTOPSIG(status) == stop_sig.
+If any other ptrace-stop is generated at the same time (for example,
+if a signal is sent to the tracee), this ptrace-stop happens.
+If none of the above applies (for example, if the tracee is running in userspace),
+it will stop with
+.B PTRACE_EVENT_STOP
+with WSTOPSIG(status) == SIGTRAP.
 .B PTRACE_INTERRUPT
 only works on tracees attached by
 .BR PTRACE_SEIZE .
@@ -760,6 +764,22 @@ and any subsequent ptrace stops will be reported under
 the thread group leader's PID.
 .SS Stopped states
 A tracee can be in two states: running or stopped.
+For the purposes of ptrace, tracee which is blocked in a syscall
+(such as
+.BR read (2),
+.BR pause (2)
+etc)
+is nevertheless considered to be running, even if tracee is blocked
+for a long time.
+The state of the tracee after
+.BR PTRACE_LISTEN
+is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands
+won't work on it, and it will deliver waitpid notifications),
+but it also may be considered "stopped" because
+it is not executing instructions (is not scheduled), and if it was
+in group-stop before
+.BR PTRACE_LISTEN ,
+it will not respond to signals until SIGCONT is received.
 .LP
 There are many kinds of states when the tracee is stopped, and in ptrace
 discussions they are often conflated.
@@ -1045,6 +1065,14 @@ then it is definitely a group-stop.
 .B SIGKILL
 killed the tracee.)
 .LP
+If tracee was attached using PTRACE_SEIZE, group-stop
+is indicated by
+.BR PTRACE_EVENT_STOP :
+status>>16 == PTRACE_EVENT_STOP. This allows detection of group-stops
+without extra
+.B PTRACE_GETSIGINFO
+call.
+.LP
 As of Linux 2.6.38,
 after the tracer sees the tracee ptrace-stop and until it
 restarts or kills it, the tracee will not run,
@@ -1170,7 +1198,7 @@ to finish exiting.
 .B PTRACE_EVENT_STOP
 Stop induced by
 .B PTRACE_INTERRUPT
-command.
+command, or group-stop (only if attached using PTRACE_SEIZE).
 .LP
 .B PTRACE_GETSIGINFO
 on
-- 
1.8.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] ptrace.2: Clarify PTRACE_INTERRUPT, PTRACE_LISTEN and group-stop behavior

[Oleg Nesterov]

On 06/20, Denys Vlasenko wrote:
>
> From: root <root-bi+AKbBUZKY6gyzm1THtWbp2dZbC/Bob@public.gmane.org>

I'll remove this guy from cc list before I reply ;)

> For easier review, here are the changes as plain text:

And thanks for the plain text.

Looks good to me. A couple of nits.

> PTRACE_INTERRUPT (since Linux 3.4)
> Stop a tracee.
> [*MODIFIED TEXT->**] If the tracee is running in kernel space
> and PTRACE_SYSCALL is in effect, it will stop with syscall-exit-stop.

Yes, but this looks a bit confusing. Or perhaps it is just me.

IOW, it looks as if PTRACE_INTERRUPT has no effect in this case, the
tracee should report syscall-exit anyway. I do not know how to explain
this better...

Perhaps. PTRACE_INTERRUPT sends the "fake" signal to the tracee (iow,
it sets TIF_SIGPENDING and wakes it up). The tracee will report
PTRACE_EVENT_STOP unless it is going to report something else
(syscall, signal).

I think it makes sense to mention that a) PTRACE_INTERRUPT is only
valid if PTRACE_SEIZE was used, and b) this is the only request which
doesn't need the stopped tracee. (PTRACE_KILL should die)

> If any other ptrace-stop is generated at the same time
> (for example, if a signal is sent to the tracee), this ptrace-stop
> happens.

Yes. Strictly speaking, do_jobctl_trap() is called before
ptrace_signal(), so this depends on the timing. So I think this
falls into "unless it is going to report something else" above.

Denys, thanks a lot for this work!

Oleg.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] ptrace.2: Clarify PTRACE_INTERRUPT, PTRACE_LISTEN and group-stop behavior

[Denys Vlasenko]

On 06/20/2013 04:24 PM, Oleg Nesterov wrote:
>> PTRACE_INTERRUPT (since Linux 3.4)
>> Stop a tracee.
>> [*MODIFIED TEXT->**] If the tracee is running in kernel space
>> and PTRACE_SYSCALL is in effect, it will stop with syscall-exit-stop.
> 
> Yes, but this looks a bit confusing. Or perhaps it is just me.
> 
> IOW, it looks as if PTRACE_INTERRUPT has no effect in this case, the
> tracee should report syscall-exit anyway. I do not know how to explain
> this better...

How about this?

"If the tracee is running or sleeping in kernel space
and PTRACE_SYSCALL is in effect, it will return from kernel
and send syscall-exit-stop notification."

I wonder whether we need to add that "The interrupted system call
will be restarted when tracee is restarted" or this is obvious
enough?

> I think it makes sense to mention that a) PTRACE_INTERRUPT is only
> valid if PTRACE_SEIZE was used, and b) this is the only request which
> doesn't need the stopped tracee. (PTRACE_KILL should die)

It is mentioned elsewhere on the man page.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] ptrace.2: Clarify PTRACE_INTERRUPT, PTRACE_LISTEN and group-stop behavior

[Oleg Nesterov]

On 06/21, Denys Vlasenko wrote:
>
> On 06/20/2013 04:24 PM, Oleg Nesterov wrote:
> >> PTRACE_INTERRUPT (since Linux 3.4)
> >> Stop a tracee.
> >> [*MODIFIED TEXT->**] If the tracee is running in kernel space
> >> and PTRACE_SYSCALL is in effect, it will stop with syscall-exit-stop.
> >
> > Yes, but this looks a bit confusing. Or perhaps it is just me.
> >
> > IOW, it looks as if PTRACE_INTERRUPT has no effect in this case, the
> > tracee should report syscall-exit anyway. I do not know how to explain
> > this better...
>
> How about this?
>
> "If the tracee is running or sleeping in kernel space
> and PTRACE_SYSCALL is in effect, it will return from kernel
> and send syscall-exit-stop notification."

Yes, perhaps... but see below.

> I wonder whether we need to add that "The interrupted system call
> will be restarted when tracee is restarted" or this is obvious
> enough?

Yes... but once again, if we document the fact that PTRACE_INTERRUPT
sends the fake signal, then we do not need to specially mention restart
of syscall-exit-stop notification above.

Just we should explain that, unless the trace has another event to
report, this fake signal results in PTRACE_EVENT_STOP(SIGTRAP).

> > I think it makes sense to mention that a) PTRACE_INTERRUPT is only
> > valid if PTRACE_SEIZE was used, and b) this is the only request which
> > doesn't need the stopped tracee. (PTRACE_KILL should die)
>
> It is mentioned elsewhere on the man page.

Ah, OK, thanks.

Oleg.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html