ptrace.2: Clarify the purpose of mentioning the kernel PTRACE_MODE_* constants

The "ptrace access mode" text is about user-space-visible
behavior, but in order to explain that behavior at what I
believe is a sufficient level of detail (e.g., to differentiate
the various types of checks that are performed for various
system calls and pseudofile accesses), one needs (1) to discuss
the MODE flag details as implemented in the kernel, and (2) to
have a shorthand way to refer to the various cases from other
pages. It's not absolutely necessary to name the flags for (1),
but using the flag names is certainly a handy shorthand for (2).

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

diff --git a/man2/ptrace.2 b/man2/ptrace.2
index fc7552b7c8992b561d884826a9f19581d1d0f112..8bbac1a7267b4fd75a249eeda3975c324ce289fa 100644 (file)
--- a/man2/ptrace.2
+++ b/man2/ptrace.2
@@ -2115,6 +2115,17 @@ or calling
 .RB ( PTRACE_MODE_ATTACH
 was effectively the default before Linux 2.6.27.)
 .PP
+Note that all of the
+.BR PTRACE_MODE_*
+constants described in this subsection are kernel-internal,
+and not visible to user space.
+The constant names are mentioned here in order to label the various kinds of
+ptrace access mode checks that are performed for various system calls
+and accesses to various pseudofiles (e.g., under
+.IR /proc ).
+These names are used in other man pages to provide a simple
+shorthand for labeling the different kernel checks.
+
 Since Linux 4.5,
 .\" commit caaee6234d05a58c5b4d05e7bf766131b810a657
 the above access mode checks may be combined (ORed) with