Hi David,
I applied pieces of this. See below.
On Fri, Mar 23, 2012 at 8:23 AM, David Prévot <taffit@xxxxxxxxxx> wrote:
> ---
> man2/ptrace.2 | 51 ++++++++++++++++++++++++++++++++-------------------
> 1 files changed, 32 insertions(+), 19 deletions(-)
>
> diff --git a/man2/ptrace.2 b/man2/ptrace.2
> index 5a8b648..457c6ac 100644
> --- a/man2/ptrace.2
> +++ b/man2/ptrace.2
> @@ -277,7 +277,7 @@ which are specified by the following flags:
> .BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)"
> When delivering system call traps, set bit 7 in the signal number
> (i.e., deliver
> -.IR "SIGTRAP|0x80" ).
> +.BR "SIGTRAP\ |\ 0x80" ).
In general, I format expressions completely in italics, so I didn't
apply this part. (And I'm sure there's some inconsistency in man-pages
on this point.)
> This makes it easy for the tracer to distinguish
> normal traps from those caused by a system call.
> .RB ( PTRACE_O_TRACESYSGOOD
> @@ -468,7 +468,7 @@ The
> .I data
> argument is treated as for
> .BR PTRACE_CONT .
> -.RI (addr
> +.RI ( addr
Applied.
> is ignored.)
> .TP
> .BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)"
> @@ -539,7 +539,9 @@ but will not necessarily have stopped
> by the completion of this call; use
> .BR waitpid (2)
> to wait for the tracee to stop.
> -See the "Attaching and detaching" subsection for additional information.
> +See the
> +.B Attaching and detaching
> +subsection for additional information.
I don't tend to format headings in bold when used inline in text, so
I've skipped this piece. (And I wonder if there is some inconsistency
in man-pages on this point.)
> .RI ( addr
> and
> .I data
> @@ -716,7 +718,9 @@ Example:
> .\" 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.
> +group-stop,
> +.B PTRACE_EVENT
> +stops, syscall-stops.
Applied.
> They all are reported by
> .BR waitpid (2)
> with
> @@ -730,7 +734,7 @@ and if there is ambiguity in that value, by querying
> .I WSTOPSIG(status)
> macro can't be used to perform this examination,
> because it returns the value
> -(\fIstatus\>>8)\ \fB&\ 0xff\fP\fP.)
> +(\fIstatus\>>8\fP)\ \fB&\ 0xff\fP.)
I agree the formatting was broken here, but I made it:
.IR "(status\>>8)\ &\ 0xff" .)
(See comments above about expressions.)
> .SS Signal-delivery-stop
> When a (possibly multithreaded) process receives any signal except
> .BR SIGKILL ,
> @@ -761,7 +765,11 @@ true, with the signal returned by
> 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.
> +see the
> +.B Syscall-stops
> +and
> +.B execve(2) under ptrace
> +sections below for details.
Not applied. See comments above.
> If
> .I WSTOPSIG(status)
> returns a stopping signal, this may be a group-stop; see below.
> @@ -837,7 +845,7 @@ The
> 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
Applied.
> only suppress signal injection, which only causes the
> .BR SIGCONT
> handler to not be executed in the tracee, if such a handler is installed).
> @@ -997,7 +1005,7 @@ with the exit signal set to
> .TP
> .B PTRACE_EVENT_CLONE
> Stop before return from
> -.BR clone (2)
> +.BR clone (2).
Applied.
> .TP
> .B PTRACE_EVENT_VFORK_DONE
> Stop before return from
> @@ -1039,12 +1047,13 @@ to finish exiting.
> on
> .B PTRACE_EVENT
> stops returns
> -.B SIGTRAP in
> +.B SIGTRAP
> +in
Already fixed by another patch (from Denys Vlasenko, I think).
> .IR si_signo ,
> with
> .I si_code
> set to
> -.IR "(event<<8)\ |\ SIGTRAP" .
> +(\fIevent<<8\fP)\ \fB|\ SIGTRAP\fP.
Not applied (see comments above).
> .SS Syscall-stops
> If the tracee was restarted by
> .BR PTRACE_SYSCALL ,
> @@ -1086,7 +1095,7 @@ If the
> option was set by the tracer, then
> .I WSTOPSIG(status)
> will give the value
> -.IR "(SIGTRAP\ |\ 0x80)" .
> +.RB ( "SIGTRAP\ |\ 0x80" ).
Not aplied.
> .LP
> Syscall-stops can be distinguished from signal-delivery-stop with
> .B SIGTRAP
> @@ -1173,7 +1182,7 @@ with
> set to
> .B SIGTRAP
> or
> -.IR (SIGTRAP|0x80) .
> +.RB ( "SIGTRAP\ |\ 0x80" ).
Not applied.
> .SS PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops
> [Details of these kinds of stops are yet to be documented.]
> .\"
> @@ -1243,7 +1252,7 @@ is
> .BR PTRACE_SINGLESTEP ,
> .BR PTRACE_SYSEMU ,
> or
> -.BR PTRACE_SYSEMU_SINGLESTEP.
> +.BR PTRACE_SYSEMU_SINGLESTEP .
Applied.
> If the tracee is in signal-delivery-stop,
> .I sig
> is the signal to be injected (if it is nonzero).
> @@ -1252,7 +1261,7 @@ Otherwise,
> 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 .)
Applied.
> .SS Attaching and detaching
> A thread can be attached to the tracer using the call
>
> @@ -1285,9 +1294,11 @@ may be lost.
> Since attaching sends
> .B SIGSTOP
> and the tracer usually suppresses it, this may cause a stray
> -.I EINTR
> +.B EINTR
Applied.
> return from the currently executing system call in the tracee,
> -as described in the "signal injection and suppression" section.
> +as described in the
> +.B Signal injection and suppression
> +section.
Not applied.
> .LP
> The request
>
> @@ -1479,10 +1490,10 @@ Example: two threads call
> 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 **
Applied. (Nice catch!)
> @@ -1539,7 +1550,9 @@ several kinds of
> notifications when the child process is traced by some other process.
> .LP
> Many of these bugs have been fixed, but as of Linux 2.6.38 several still
> -exist; see BUGS below.
> +exist; see
> +.B BUGS
> +below.
Not applied.
> .LP
> As of Linux 2.6.38, the following is believed to work correctly:
> .IP * 3
> --
> 1.7.9.1
>
Thanks for this David!
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
