ptrace.2: Tweaks to Keno Fischer's patches

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/ptrace.2

@@ -646,8 +646,10 @@ value such that
 
 While this triggers a
 .BR PTRACE_EVENT
-stop, it is similar to a syscall-enter-stop. For details,
-see the note on PTRACE_EVENT_SECCOMP below.
+stop, it is similar to a syscall-enter-stop.
+For details, see the note on
+.B PTRACE_EVENT_SECCOMP
+below.
 The seccomp event message data (from the
 .BR SECCOMP_RET_DATA
 portion of the seccomp filter rule) can be retrieved with
@@ -737,7 +739,8 @@ is ignored.)
 For
 .BR PTRACE_SYSEMU ,
 continue and stop on entry to the next system call,
-which will not be executed. See the documentation on syscall-stops below.
+which will not be executed.
+See the documentation on syscall-stops below.
 For
 .BR PTRACE_SYSEMU_SINGLESTEP ,
 do the same but also singlestep if not a system call.
@@ -1554,7 +1557,8 @@ has been set by the tracer.
 The seccomp event message data (from the
 .BR SECCOMP_RET_DATA
 portion of the seccomp filter rule) can be retrieved with
-.BR PTRACE_GETEVENTMSG . The semantics of this stop are described in
+.BR PTRACE_GETEVENTMSG .
+The semantics of this stop are described in
 detail in a separate section below.
 .LP
 .B PTRACE_GETSIGINFO
@@ -1576,7 +1580,7 @@ or
 the tracee enters
 syscall-enter-stop just prior to entering any system call (which
 will not be executed if the restart was using
-.BR PTRACE_SYSEMU,
+.BR PTRACE_SYSEMU ,
 regardless of any change made to registers at this point or how the
 tracee is restarted after this stop).
 No matter which method caused the syscall-entry-stop,
@@ -1587,11 +1591,11 @@ or if it is interrupted by a signal.
 (That is, signal-delivery-stop never happens between syscall-enter-stop
 and syscall-exit-stop; it happens
 .I after
-syscall-exit-stop.). If the tracee is continued using any other method
-(
-including
-.BR PTRACE_SYSEMU
-), no syscall-exit-stop occurs. Note that all mentions
+syscall-exit-stop.).
+If the tracee is continued using any other method (including
+.BR PTRACE_SYSEMU ),
+no syscall-exit-stop occurs.
+Note that all mentions
 .BR PTRACE_SYSEMU
 apply equally to
 .BR PTRACE_SYSEMU_SINGLESTEP.
@@ -1692,14 +1696,15 @@ indistinguishable from each other by the tracer.
 The tracer needs to keep track of the sequence of
 ptrace-stops in order to not misinterpret syscall-enter-stop as
 syscall-exit-stop or vice versa.
-In general a syscall-enter-stop is
+In general, a syscall-enter-stop is
 always followed by syscall-exit-stop,
 .B PTRACE_EVENT
-stop or the tracee's death;
+stop, or the tracee's death;
 no other kinds of ptrace-stop can occur in between.
 However, note that seccomp stops (see below) can cause syscall-exit-stops,
-without preceeding syscall-entry-stops. If seccomp is in use, care needs
-to be taken not to mis-interpret such stops as syscall-entry-stops.
+without preceeding syscall-entry-stops.
+If seccomp is in use, care needs
+to be taken not to misinterpret such stops as syscall-entry-stops.
 .LP
 If after syscall-enter-stop,
 the tracer uses a restarting command other than
@@ -1717,75 +1722,83 @@ set to
 .B SIGTRAP
 or
 .IR (SIGTRAP|0x80) .
-.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 - 4.7)
+.\"
+.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to 4.7)
 The behavior of
 .BR PTRACE_EVENT_SECCOMP
 stops and their interaction with other kinds
-of ptrace stops has changed between kernel versions. This documents the behavior
-from their introduction until Linux 4.7 (inclusive). The behavior in later kernel
-versions is documented in the next section.
+of ptrace stops has changed between kernel versions.
+This documents the behavior
+from their introduction until Linux 4.7 (inclusive).
+The behavior in later kernel versions is documented in the next section.
 
 A
 .BR PTRACE_EVENT_SECCOMP
 stop occurs whenever a
 .BR SECCOMP_RET_TRACE
-rule is triggered. This is independent of which methods was used to restart
-the system call. Notably, seccomp still runs even if the tracee
-was restarted using
+rule is triggered.
+This is independent of which methods was used to restart the system call.
+Notably, seccomp still runs even if the tracee was restarted using
 .BR PTRACE_SYSEMU
 and this system call is unconditionally skipped.
 
 Restarts from this stop will behave as if the stop had occurred right
-before the system call in question. In particular, both
+before the system call in question.
+In particular, both
 .BR PTRACE_SYSCALL
 and
 .BR PTRACE_SYSEMU
-will normally cause a subsequent syscall-entry-stop. However, if after the
+will normally cause a subsequent syscall-entry-stop.
+However, if after the
 .BR PTRACE_EVENT_SECCOMP
-the system call number is negative, both the syscall-entry-stop
-and the system call itself will be skipped. This means that if the
-system call number is negative after a
+the system call number is negative,
+both the syscall-entry-stop and the system call itself will be skipped.
+This means that if the system call number is negative after a
 .BR PTRACE_EVENT_SECCOMP
 and the tracee is restarted using
 .BR PTRACE_SYSCALL,
 the next observed stop will be a syscall-exit-stop,
-rather than the syscall-entry-stop
-that may have been expected.
-
-.SS PTRACE_EVENT_SECCOMP stops (Linux 4.8+)
-
-In Linux 4.8, the
+rather than the syscall-entry-stop that might have been expected.
+.\"
+.SS PTRACE_EVENT_SECCOMP stops (since Linux 4.8)
+Starting with Linux 4.8,
+.\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea
+the
 .BR PTRACE_EVENT_SECCOMP
-stop was re-ordered to occur between syscall-entry-stop and
-syscall-exit-stop. Note that, seccomp no longer
-runs (and no `PTRACE_EVENT_SECCOMP` will be reported) if
-the system call is skipped
-due to
-.BR PTRACE_SYSEMU
-.
+stop was reordered to occur between syscall-entry-stop and
+syscall-exit-stop.
+Note that seccomp no longer runs (and no
+.B PTRACE_EVENT_SECCOMP
+will be reported) if the system call is skipped due to
+.BR PTRACE_SYSEMU .
 
-Functionally, a PTRACE_EVENT_SECCOMP stop functions comparably
-to a syscall-entry-stop (i.e. continuations using
+Functionally, a
+.B PTRACE_EVENT_SECCOMP
+stop functions comparably
+to a syscall-entry-stop (i.e., continuations using
 .BR PTRACE_SYSCALL
-will cause syscall-exit-stops, the system call number may be changed
-and any other modified registers are visible to the to-be-executed syscall as well).
-Note that there may, but need not have been a preceeding syscall-entry-stop.
+will cause syscall-exit-stops,
+the system call number may be changed and any other modified registers
+are visible to the to-be-executed system call as well).
+Note that there may be,
+but need not have been a preceeding syscall-entry-stop.
 
 After a
 .BR PTRACE_EVENT_SECCOMP
-stop, seccomp will be re-run, with a
+stop, seccomp will be rerun, with a
 .BR SECCOMP_RET_TRACE
 rule now functioning the same as a
-.BR SECCOMP_RET_ALLOW
-. Specifically, this means that if registers are not modified during the
+.BR SECCOMP_RET_ALLOW .
+Specifically, this means that if registers are not modified during the
 .BR PTRACE_EVENT_SECCOMP
 stop, the system call will then be allowed.
-
+.\"
 .SS PTRACE_SINGLESTEP stops
 [Details of these kinds of stops are yet to be documented.]
 .\"
 .\" FIXME .
 .\" document stops occurring with PTRACE_SINGLESTEP
+.\"
 .SS Informational and restarting ptrace commands
 Most ptrace commands (all except
 .BR PTRACE_ATTACH ,