[PATCH 00/14] prctl.2 man page updates for Linux 5.6

[PATCH 00/14] prctl.2 man page updates for Linux 5.6

[Dave Martin]

A bunch of updates to the prctl(2) man page to fill in the missing
prctls (mostly) up to Linux 5.6 (along with a few other tweaks fixes).

People not Cc'd on the whole series can find the whole series at
https://lore.kernel.org/linux-man/ .

Patches:

 * Patches 1-6 and 8-9 are rather trivial optional tweaks and fixes
   that don't make substantive changes.  I can live with some of these
   being dropped.

 * Patch 7 (removal of the MPX prctls) could use an Ack, but should be
   uncontroversial.

 * Patches 10-11 cover recent extensions to the speculation control
   prctls.

 * Patch 12 adds one particular case Errors for EINVAL, applicable to
   all arch-specific prctls.  I've not tried too hard to be 100%
   comprehensive with the error conditions, since the list in its
   current form looks in need of a major overhaul.

 * Patches 13-14 add the new arm64-specific prctls.
   (PR_SET_TAGGED_ADDR_CTRL requires a bit more discussion and will be
   posted separately.)

Maintainer notes:

 * I'm *asssuming* that the datestamps in .TH are automatically
   updated by maintainer scripts, since maintaining them by hand would
   interact very badly with rebase.  If needed I can go update them by
   hand though.

 * Similarly, in the days of git (and because I see no recent entries)
   I'm assuming that in-file changelogs no longer need to be updated.
   Again, I'm happy to do that if needed.


Dave Martin (14):
  prctl.2: tfix clarify that prctl can apply to threads
  prctl.2: Add health warning
  prctl.2: tfix mis-description of thread ID values in procfs
  prctl.2: srcfix add comments for navigation
  prctl.2: tfix listing order of prctls
  prctl.2: ffix quotation mark tweaks
  prctl.2: Document removal of Intel MPX prctls
  prctl.2: Work around bogus constant "maxsig" in PR_SET_PDEATHSIG
  prctl.2: tfix minor punctuation in SPECULATION_CTRL prctls
  prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls
  prctl.2: Add PR_SPEC_DISABLE_NOEXEC for SPECULATION_CTRL prctls
  prctl.2: Clarify the unsupported hardware case of EINVAL
  prctl.2: Add SVE prctls (arm64)
  prctl.2: Add PR_PAC_RESET_KEYS (arm64)

 man2/prctl.2 | 496 +++++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 384 insertions(+), 112 deletions(-)

-- 
2.1.4

[PATCH 01/14] prctl.2: tfix clarify that prctl can apply to threads

[Dave Martin]

The current synopsis for prctl(2) misleadingly claims that prctl
operates on a process.  Rather, some (in fact, most) prctls operate
on a thread.

The wording probably dates back to the old days when Linux didn't
really have threads at all.

Reword as appropriate.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
---
 man2/prctl.2 | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 7a5af76..7932ada 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -53,7 +53,7 @@
 .\"
 .TH PRCTL 2 2020-04-11 "Linux" "Linux Programmer's Manual"
 .SH NAME
-prctl \- operations on a process
+prctl \- operations on a process or thread
 .SH SYNOPSIS
 .nf
 .B #include <sys/prctl.h>
@@ -63,6 +63,10 @@ prctl \- operations on a process
 .fi
 .SH DESCRIPTION
 .BR prctl ()
+manipulates various aspects of the behavior
+of the calling thread or process.
+.PP
+.BR prctl ()
 is called with a first argument describing what to do
 (with values defined in \fI<linux/prctl.h>\fP), and further
 arguments with a significance depending on the first one.
-- 
2.1.4

Re: [PATCH 01/14] prctl.2: tfix clarify that prctl can apply to threads

[Michael Kerrisk (man-pages)]

On 5/12/20 6:36 PM, Dave Martin wrote:
> The current synopsis for prctl(2) misleadingly claims that prctl
> operates on a process.  Rather, some (in fact, most) prctls operate
> on a thread.
> 
> The wording probably dates back to the old days when Linux didn't
> really have threads at all.
> 
> Reword as appropriate.

Thanks, Dave. Patch applied.

Cheers,

Michael

> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> ---
>  man2/prctl.2 | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 7a5af76..7932ada 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -53,7 +53,7 @@
>  .\"
>  .TH PRCTL 2 2020-04-11 "Linux" "Linux Programmer's Manual"
>  .SH NAME
> -prctl \- operations on a process
> +prctl \- operations on a process or thread
>  .SH SYNOPSIS
>  .nf
>  .B #include <sys/prctl.h>
> @@ -63,6 +63,10 @@ prctl \- operations on a process
>  .fi
>  .SH DESCRIPTION
>  .BR prctl ()
> +manipulates various aspects of the behavior
> +of the calling thread or process.
> +.PP
> +.BR prctl ()
>  is called with a first argument describing what to do
>  (with values defined in \fI<linux/prctl.h>\fP), and further
>  arguments with a significance depending on the first one.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 02/14] prctl.2: Add health warning

[Dave Martin]

In reality, almost every prctl interferes with assumptions that the
compiler and C library / runtime rely on.  prctl() can therefore
make userspace explode in a variety ways that are likely to be hard
to debug.

This is not obvious to the uninitiated, so add a warning.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
---
 man2/prctl.2 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 7932ada..a35b748 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -66,6 +66,11 @@ prctl \- operations on a process or thread
 manipulates various aspects of the behavior
 of the calling thread or process.
 .PP
+Note that careless use of
+.BR prctl ()
+can confuse the userspace run-time environment,
+so these operations should be used with care (if at all).
+.PP
 .BR prctl ()
 is called with a first argument describing what to do
 (with values defined in \fI<linux/prctl.h>\fP), and further
-- 
2.1.4

Re: [PATCH 02/14] prctl.2: Add health warning

[Michael Kerrisk (man-pages)]

Hi Dave,

On 5/12/20 6:36 PM, Dave Martin wrote:
> In reality, almost every prctl interferes with assumptions that the
> compiler and C library / runtime rely on.  prctl() can therefore
> make userspace explode in a variety ways that are likely to be hard
> to debug.
> 
> This is not obvious to the uninitiated, so add a warning.

Patch applied. But see my comments on patch 04. I may want to 
circle back on this patch later, since the wording feels a 
little strong to me (we simply must use prctl for some things, 
and not all of those things break user-space/runtime as far 
as I know). If you have some thoughts on softening the warning,
let me know.

Cheers,

Michael

> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> ---
>  man2/prctl.2 | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 7932ada..a35b748 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -66,6 +66,11 @@ prctl \- operations on a process or thread
>  manipulates various aspects of the behavior
>  of the calling thread or process.
>  .PP
> +Note that careless use of
> +.BR prctl ()
> +can confuse the userspace run-time environment,
> +so these operations should be used with care (if at all).
> +.PP
>  .BR prctl ()
>  is called with a first argument describing what to do
>  (with values defined in \fI<linux/prctl.h>\fP), and further
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 02/14] prctl.2: Add health warning

[Dave Martin]

On Wed, May 13, 2020 at 12:10:25PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
> 
> On 5/12/20 6:36 PM, Dave Martin wrote:
> > In reality, almost every prctl interferes with assumptions that the
> > compiler and C library / runtime rely on.  prctl() can therefore
> > make userspace explode in a variety ways that are likely to be hard
> > to debug.
> > 
> > This is not obvious to the uninitiated, so add a warning.
> 
> Patch applied. But see my comments on patch 04. I may want to 
> circle back on this patch later, since the wording feels a 
> little strong to me (we simply must use prctl for some things, 
> and not all of those things break user-space/runtime as far 
> as I know). If you have some thoughts on softening the warning,
> let me know.

Certainly the "if at all" can go -- this was just a suggestion
really.

Maybe the whole thing is superfluous.  In C anything can screw up the
runtime if you try hard enough.


The background to this patch is that things like the new
PR_PAC_RESET_KEYS and PR_SVE_SET_VL are likely to crash the program, or
place a timebomb that will explode later when someone upgrades their
toolchain or links with a new version of some library.  Many existing
prctls that look equally unfriendly...

I didn't want to say nothing at all, but I didn't want to get into the
gory details either.

Doing the digging to document the safety requirements of each prctl
would be a lot of work, and probably an exercise in futility anyway --
how to use a lot of prctls safely depends on the run-time environment as
much as it does on the kernel.


If you want to drop this, I'm happy to add explicit notes to just the
new arm64 prctls instead for now.

Cheers
---Dave

Re: [PATCH 02/14] prctl.2: Add health warning

[Michael Kerrisk (man-pages)]

Hi Dave,

On 5/13/20 1:13 PM, Dave Martin wrote:
> On Wed, May 13, 2020 at 12:10:25PM +0200, Michael Kerrisk (man-pages) wrote:
>> Hi Dave,
>>
>> On 5/12/20 6:36 PM, Dave Martin wrote:
>>> In reality, almost every prctl interferes with assumptions that the
>>> compiler and C library / runtime rely on.  prctl() can therefore
>>> make userspace explode in a variety ways that are likely to be hard
>>> to debug.
>>>
>>> This is not obvious to the uninitiated, so add a warning.
>>
>> Patch applied. But see my comments on patch 04. I may want to 
>> circle back on this patch later, since the wording feels a 
>> little strong to me (we simply must use prctl for some things, 
>> and not all of those things break user-space/runtime as far 
>> as I know). If you have some thoughts on softening the warning,
>> let me know.
> 
> Certainly the "if at all" can go -- this was just a suggestion
> really.

Yes. Gone.

> Maybe the whole thing is superfluous.  In C anything can screw up the
> runtime if you try hard enough.

I think it's at least worth alerting the reader to this issue.

> The background to this patch is that things like the new
> PR_PAC_RESET_KEYS and PR_SVE_SET_VL are likely to crash the program, or
> place a timebomb that will explode later when someone upgrades their
> toolchain or links with a new version of some library.  Many existing
> prctls that look equally unfriendly...
> 
> I didn't want to say nothing at all, but I didn't want to get into the
> gory details either.

(Okay.)

> Doing the digging to document the safety requirements of each prctl
> would be a lot of work, and probably an exercise in futility anyway --
> how to use a lot of prctls safely depends on the run-time environment as
> much as it does on the kernel.
> 
> 
> If you want to drop this, I'm happy to add explicit notes to just the
> new arm64 prctls instead for now.

I just softened the warning a little; see below. Explicit notes for
the new arm64 prctls would certainly be welcome.

Cheers,

Michael

diff --git a/man2/prctl.2 b/man2/prctl.2
index 7e78fc3c1..4e2d67345 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -66,10 +66,10 @@ prctl \- operations on a process or thread
 manipulates various aspects of the behavior
 of the calling thread or process.
 .PP
-Note that careless use of
+Note that careless use of some
 .BR prctl ()
-can confuse the user-space run-time environment,
-so these operations should be used with care (if at all).
+operations can confuse the user-space run-time environment,
+so these operations should be used with care.
 .PP
 .BR prctl ()
 is called with a first argument describing what to do



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 02/14] prctl.2: Add health warning

[Dave Martin]

On Wed, May 13, 2020 at 01:40:26PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
> 
> On 5/13/20 1:13 PM, Dave Martin wrote:
> > On Wed, May 13, 2020 at 12:10:25PM +0200, Michael Kerrisk (man-pages) wrote:
> >> Hi Dave,
> >>
> >> On 5/12/20 6:36 PM, Dave Martin wrote:
> >>> In reality, almost every prctl interferes with assumptions that the
> >>> compiler and C library / runtime rely on.  prctl() can therefore
> >>> make userspace explode in a variety ways that are likely to be hard
> >>> to debug.
> >>>
> >>> This is not obvious to the uninitiated, so add a warning.
> >>
> >> Patch applied. But see my comments on patch 04. I may want to 
> >> circle back on this patch later, since the wording feels a 
> >> little strong to me (we simply must use prctl for some things, 
> >> and not all of those things break user-space/runtime as far 
> >> as I know). If you have some thoughts on softening the warning,
> >> let me know.
> > 
> > Certainly the "if at all" can go -- this was just a suggestion
> > really.
> 
> Yes. Gone.
> 
> > Maybe the whole thing is superfluous.  In C anything can screw up the
> > runtime if you try hard enough.
> 
> I think it's at least worth alerting the reader to this issue.
> 
> > The background to this patch is that things like the new
> > PR_PAC_RESET_KEYS and PR_SVE_SET_VL are likely to crash the program, or
> > place a timebomb that will explode later when someone upgrades their
> > toolchain or links with a new version of some library.  Many existing
> > prctls that look equally unfriendly...
> > 
> > I didn't want to say nothing at all, but I didn't want to get into the
> > gory details either.
> 
> (Okay.)
> 
> > Doing the digging to document the safety requirements of each prctl
> > would be a lot of work, and probably an exercise in futility anyway --
> > how to use a lot of prctls safely depends on the run-time environment as
> > much as it does on the kernel.
> > 
> > 
> > If you want to drop this, I'm happy to add explicit notes to just the
> > new arm64 prctls instead for now.
> 
> I just softened the warning a little; see below. Explicit notes for
> the new arm64 prctls would certainly be welcome.

OK, that works for me.  I'll try to keep it brief.

Cheers
---Dave

[PATCH 03/14] prctl.2: tfix mis-description of thread ID values in procfs

[Dave Martin]

Under PR_SET_NAME, the [tid] value seen in procfs as
/proc/self/task/[tid] is mistakenly described as the name of the
thread, whereas really the name is on /proc/self/task/[tid]/comm.

Fix it.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
---
 man2/prctl.2 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index a35b748..9736434 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -808,8 +808,10 @@ and retrieved using
 The attribute is likewise accessible via
 .IR /proc/self/task/[tid]/comm ,
 where
-.I tid
-is the name of the calling thread.
+.I [tid]
+is the the thread ID of the calling thread, as returned by
+.BR gettid (2).
+.\" prctl PR_GET_NAME
 .TP
 .BR PR_GET_NAME " (since Linux 2.6.11)"
 Return the name of the calling thread,
-- 
2.1.4

Re: [PATCH 03/14] prctl.2: tfix mis-description of thread ID values in procfs

[Michael Kerrisk (man-pages)]

On 5/12/20 6:36 PM, Dave Martin wrote:
> Under PR_SET_NAME, the [tid] value seen in procfs as
> /proc/self/task/[tid] is mistakenly described as the name of the
> thread, whereas really the name is on /proc/self/task/[tid]/comm.
> 
> Fix it.

Thanks, Dave. Patch applied.

Cheers,

Michael

> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> ---
>  man2/prctl.2 | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index a35b748..9736434 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -808,8 +808,10 @@ and retrieved using
>  The attribute is likewise accessible via
>  .IR /proc/self/task/[tid]/comm ,
>  where
> -.I tid
> -is the name of the calling thread.
> +.I [tid]
> +is the the thread ID of the calling thread, as returned by
> +.BR gettid (2).
> +.\" prctl PR_GET_NAME
>  .TP
>  .BR PR_GET_NAME " (since Linux 2.6.11)"
>  Return the name of the calling thread,
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 04/14] prctl.2: srcfix add comments for navigation

[Dave Martin]

The prctl.2 source is unnecessarily hard to navigate, not least
because prctl option flags are traditionally named PR_* and so look
just like prctl names.

For each actual prctl, add a comment of the form

	.\" prctl PR_FOO

to make it move obvious where each top-level prctl starts.

Of course, we could add some clever macros, but let's not confuse
dumb parsers.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
---
 man2/prctl.2 | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 9736434..e5b2b4b 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -77,6 +77,7 @@ is called with a first argument describing what to do
 arguments with a significance depending on the first one.
 The first argument can be:
 .\"
+.\" prctl PR_CAP_AMBIENT
 .TP
 .BR PR_CAP_AMBIENT " (since Linux 4.3)"
 .\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08
@@ -130,6 +131,7 @@ library in the form of
 .BR cap_set_ambient (3),
 and
 .BR cap_reset_ambient (3).
+.\" prctl PR_CAPBSET_READ
 .TP
 .BR PR_CAPBSET_READ " (since Linux 2.6.25)"
 Return (as the function result) 1 if the capability specified in
@@ -152,6 +154,7 @@ A higher-level interface layered on top of this operation is provided in the
 .BR libcap (3)
 library in the form of
 .BR cap_get_bound (3).
+.\" prctl PR_CAPBSET_DROP
 .TP
 .BR PR_CAPBSET_DROP " (since Linux 2.6.25)"
 If the calling thread has the
@@ -178,6 +181,7 @@ A higher-level interface layered on top of this operation is provided in the
 .BR libcap (3)
 library in the form of
 .BR cap_drop_bound (3).
+.\" prctl PR_SET_CHILD_SUBREAPER
 .TP
 .BR PR_SET_CHILD_SUBREAPER " (since Linux 3.4)"
 .\" commit ebec18a6d3aa1e7d84aab16225e87fd25170ec2b
@@ -224,11 +228,13 @@ Some
 frameworks (e.g.,
 .BR systemd (1))
 employ a subreaper process for similar reasons.
+.\" prctl PR_GET_CHILD_SUBREAPER
 .TP
 .BR PR_GET_CHILD_SUBREAPER " (since Linux 3.4)"
 Return the "child subreaper" setting of the caller,
 in the location pointed to by
 .IR "(int\ *) arg2" .
+.\" prctl PR_SET_DUMPABLE
 .TP
 .BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
 Set the state of the "dumpable" attribute,
@@ -297,6 +303,7 @@ the ownership of files in the process's
 .IR /proc/[pid]
 directory is affected as described in
 .BR proc (5).
+.\" prctl PR_GET_DUMPABLE
 .TP
 .BR PR_GET_DUMPABLE " (since Linux 2.3.20)"
 Return (as the function result) the current state of the calling
@@ -304,6 +311,7 @@ process's dumpable attribute.
 .\" Since Linux 2.6.13, the dumpable flag can have the value 2,
 .\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
 .\" flags has a nonzero value.  This was fixed in 2.6.14.
+.\" prctl PR_SET_ENDIAN
 .TP
 .BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
 Set the endian-ness of the calling process to the value given
@@ -314,11 +322,13 @@ in \fIarg2\fP, which should be one of the following:
 or
 .B PR_ENDIAN_PPC_LITTLE
 (PowerPC pseudo little endian).
+.\" prctl PR_GET_ENDIAN
 .TP
 .BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
 Return the endian-ness of the calling process,
 in the location pointed to by
 .IR "(int\ *) arg2" .
+.\" prctl PR_SET_FP_MODE
 .TP
 .BR PR_SET_FP_MODE " (since Linux 4.0, only on MIPS)"
 .\" commit 9791554b45a2acc28247f66a5fd5bbc212a6b8c8
@@ -425,6 +435,7 @@ The arguments
 and
 .IR arg5
 are ignored.
+.\" prctl PR_GET_FP_MODE
 .TP
 .BR PR_GET_FP_MODE " (since Linux 4.0, only on MIPS)"
 Return (as the function result)
@@ -442,6 +453,7 @@ The arguments
 and
 .IR arg5
 are ignored.
+.\" prctl PR_SET_FPEMU
 .TP
 .BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
 Set floating-point emulation control bits to \fIarg2\fP.
@@ -452,11 +464,13 @@ to silently emulate floating-point operation accesses, or
 to not emulate floating-point operations and send
 .B SIGFPE
 instead.
+.\" prctl PR_GET_FPEMU
 .TP
 .BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
 Return floating-point emulation control bits,
 in the location pointed to by
 .IR "(int\ *) arg2" .
+.\" prctl PR_SET_FPEXC
 .TP
 .BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
 Set floating-point exception mode to \fIarg2\fP.
@@ -470,11 +484,13 @@ Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
 \fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode,
 \fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode,
 \fBPR_FP_EXC_PRECISE\fP for precise exception mode.
+.\" prctl PR_GET_FPEXC
 .TP
 .BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
 Return floating-point exception mode,
 in the location pointed to by
 .IR "(int\ *) arg2" .
+.\" prctl PR_SET_KEEPCAPS
 .TP
 .BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
 Set the state of the calling thread's "keep capabilities" flag.
@@ -485,6 +501,7 @@ must be either 0 (clear the flag)
 or 1 (set the flag).
 The "keep capabilities" value will be reset to 0 on subsequent calls to
 .BR execve (2).
+.\" prctl PR_GET_KEEPCAPS
 .TP
 .BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
 Return (as the function result) the current state of the calling thread's
@@ -492,6 +509,7 @@ Return (as the function result) the current state of the calling thread's
 See
 .BR capabilities (7)
 for a description of this flag.
+.\" prctl PR_MCE_KILL
 .TP
 .BR PR_MCE_KILL " (since Linux 2.6.32)"
 Set the machine check memory corruption kill policy for the calling thread.
@@ -532,6 +550,7 @@ The policy is inherited by children.
 The remaining unused
 .BR prctl ()
 arguments must be zero for future compatibility.
+.\" prctl PR_MCE_KILL_GET
 .TP
 .BR PR_MCE_KILL_GET " (since Linux 2.6.32)"
 Return (as the function result)
@@ -539,6 +558,7 @@ the current per-process machine check kill policy.
 All unused
 .BR prctl ()
 arguments must be zero.
+.\" prctl PR_SET_MM
 .TP
 .BR PR_SET_MM " (since Linux 3.3)"
 .\" commit 028ee4be34a09a6d48bdf30ab991ae933a7bc036
@@ -716,6 +736,7 @@ This feature is available only if the kernel is built with the
 .BR CONFIG_CHECKPOINT_RESTORE
 option enabled.
 .RE
+.\" prctl PR_MPX_ENABLE_MANAGEMENT
 .TP
 .BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19) "
 .\" commit fe3d197f84319d3bce379a9c0dc17b1f48ad358c
@@ -791,6 +812,7 @@ had been called.
 .IP
 For further information on Intel MPX, see the kernel source file
 .IR Documentation/x86/intel_mpx.txt .
+.\" prctl PR_SET_NAME
 .TP
 .BR PR_SET_NAME " (since Linux 2.6.9)"
 Set the name of the calling thread,
@@ -819,6 +841,7 @@ in the buffer pointed to by
 .IR "(char\ *) arg2" .
 The buffer should allow space for up to 16 bytes;
 the returned string will be null-terminated.
+.\" prctl PR_SET_NO_NEW_PRIVS
 .TP
 .BR PR_SET_NO_NEW_PRIVS " (since Linux 3.5)"
 Set the calling thread's
@@ -862,6 +885,7 @@ For more information, see the kernel source file
 before Linux 4.13).
 See also
 .BR seccomp (2).
+.\" prctl PR_GET_NO_NEW_PRIVS
 .TP
 .BR PR_GET_NO_NEW_PRIVS " (since Linux 3.5)"
 Return (as the function result) the value of the
@@ -873,6 +897,7 @@ behavior.
 A value of 1 indicates
 .BR execve (2)
 will operate in the privilege-restricting mode described above.
+.\" prctl PR_SET_PDEATHSIG
 .TP
 .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
 Set the parent-death signal
@@ -922,11 +947,13 @@ or a binary that has associated capabilities (see
 .BR capabilities (7));
 otherwise, this value is preserved across
 .BR execve (2).
+.\" prctl PR_GET_PDEATHSIG
 .TP
 .BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
 Return the current value of the parent process death signal,
 in the location pointed to by
 .IR "(int\ *) arg2" .
+.\" prctl PR_SET_PTRACER
 .TP
 .BR PR_SET_PTRACER " (since Linux 3.4)"
 .\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
@@ -959,6 +986,7 @@ For further information, see the kernel source file
 (or
 .IR Documentation/security/Yama.txt
 before Linux 4.13).
+.\" prctl PR_SET_SECCOMP
 .TP
 .BR PR_SET_SECCOMP " (since Linux 2.6.23)"
 .\" See http://thread.gmane.org/gmane.linux.kernel/542632
@@ -1035,6 +1063,7 @@ For further information, see the kernel source file
 (or
 .IR Documentation/prctl/seccomp_filter.txt
 before Linux 4.13).
+.\" prctl PR_GET_SECCOMP
 .TP
 .BR PR_GET_SECCOMP " (since Linux 2.6.23)"
 Return (as the function result)
@@ -1061,18 +1090,21 @@ field of the
 file provides a method of obtaining the same information,
 without the risk that the process is killed; see
 .BR proc (5).
+.\" prctl PR_SET_SECUREBITS
 .TP
 .BR PR_SET_SECUREBITS " (since Linux 2.6.26)"
 Set the "securebits" flags of the calling thread to the value supplied in
 .IR arg2 .
 See
 .BR capabilities (7).
+.\" prctl PR_GET_SECUREBITS
 .TP
 .BR PR_GET_SECUREBITS " (since Linux 2.6.26)"
 Return (as the function result)
 the "securebits" flags of the calling thread.
 See
 .BR capabilities (7).
+.\" prctl PR_GET_SPECULATION_CTRL
 .TP
 .BR PR_GET_SPECULATION_CTRL " (since Linux 4.17)"
 Return (as the function result)
@@ -1119,6 +1151,7 @@ and
 .I arg5
 arguments must be specified as 0; otherwise the call fails with the error
 .BR EINVAL .
+.\" prctl PR_SET_SPECULATION_CTRL
 .TP
 .BR PR_SET_SPECULATION_CTRL " (since Linux 4.17)"
 .\" commit b617cfc858161140d69cc0b5cc211996b557a1c7
@@ -1174,6 +1207,7 @@ call failing with the error
 .BR ENXIO .
 For further details, see the kernel source file
 .IR Documentation/admin-guide/kernel-parameters.txt .
+.\" prctl PR_SET_THP_DISABLE
 .TP
 .BR PR_SET_THP_DISABLE " (since Linux 3.15)"
 .\" commit a0715cc22601e8830ace98366c0c2bd8da52af52
@@ -1191,6 +1225,7 @@ The setting of the "THP disable" flag is inherited by a child created via
 and is preserved across
 .BR execve (2).
 .\"
+.\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
 .BR PR_TASK_PERF_EVENTS_DISABLE " (since Linux 2.6.31)"
 Disable all performance counters attached to the calling process,
@@ -1207,6 +1242,7 @@ Originally called
 renamed (retaining the same numerical value)
 in Linux 2.6.32.
 .\"
+.\" prctl PR_TASK_PERF_EVENTS_ENABLE
 .TP
 .BR PR_TASK_PERF_EVENTS_ENABLE " (since Linux 2.6.31)"
 The converse of
@@ -1220,11 +1256,13 @@ renamed
 .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
 in Linux 2.6.32.
 .\"
+.\" prctl PR_GET_THP_DISABLE
 .TP
 .BR PR_GET_THP_DISABLE " (since Linux 3.15)"
 Return (as the function result) the current setting of the "THP disable"
 flag for the calling thread:
 either 1, if the flag is set, or 0, if it is not.
+.\" prctl PR_GET_TID_ADDRESS
 .TP
 .BR PR_GET_TID_ADDRESS " (since Linux 3.5)"
 .\" commit 300f786b2683f8bb1ec0afb6e1851183a479c86d
@@ -1246,6 +1284,7 @@ system call does not have a compat implementation for
 the AMD64 x32 and MIPS n32 ABIs,
 and the kernel writes out a pointer using the kernel's pointer size,
 this operation expects a user-space buffer of 8 (not 4) bytes on these ABIs.
+.\" prctl PR_SET_TIMERSLACK
 .TP
 .BR PR_SET_TIMERSLACK " (since Linux 2.6.28)"
 .\" See https://lwn.net/Articles/369549/
@@ -1316,10 +1355,12 @@ can be examined and changed via the file
 .IR /proc/[pid]/timerslack_ns .
 See
 .BR proc (5).
+.\" prctl PR_GET_TIMERSLACK
 .TP
 .BR PR_GET_TIMERSLACK " (since Linux 2.6.28)"
 Return (as the function result)
 the "current" timer slack value of the calling thread.
+.\" prctl PR_SET_TIMING
 .TP
 .BR PR_SET_TIMING " (since Linux 2.6.0)"
 .\" Precisely: Linux 2.6.0-test4
@@ -1338,11 +1379,13 @@ is not currently implemented
 .\" PR_TIMING_TIMESTAMP doesn't do anything in 2.6.26-rc8,
 .\" and looking at the patch history, it appears
 .\" that it never did anything.
+.\" prctl PR_GET_TIMING
 .TP
 .BR PR_GET_TIMING " (since Linux 2.6.0)"
 .\" Precisely: Linux 2.6.0-test4
 Return (as the function result) which process timing method is currently
 in use.
+.\" prctl PR_SET_TSC
 .TP
 .BR PR_SET_TSC " (since Linux 2.6.26, x86 only)"
 Set the state of the flag determining whether the timestamp counter
@@ -1356,12 +1399,14 @@ to allow it to be read, or
 to generate a
 .B SIGSEGV
 when the process tries to read the timestamp counter.
+.\" prctl PR_GET_TSC
 .TP
 .BR PR_GET_TSC " (since Linux 2.6.26, x86 only)"
 Return the state of the flag determining whether the timestamp counter
 can be read,
 in the location pointed to by
 .IR "(int\ *) arg2" .
+.\" prctl PR_SET_UNALIGN
 .TP
 .B PR_SET_UNALIGN
 (Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15;
@@ -1385,6 +1430,7 @@ flag in
 operation of the
 .BR setsysinfo ()
 system call on Tru64).
+.\" prctl PR_GET_UNALIGN
 .TP
 .B PR_GET_UNALIGN
 (See
@@ -1392,6 +1438,7 @@ system call on Tru64).
 for information on versions and architectures.)
 Return unaligned access control bits, in the location pointed to by
 .IR "(unsigned int\ *) arg2" .
+.\" prctl PR_SET_IO_FLUSHER
 .TP
 .BR PR_SET_IO_FLUSHER " (since Linux 5.6)"
 If a user process is involved in the block layer or filesystem I/O path,
@@ -1420,6 +1467,7 @@ and is preserved across
 Examples of IO_FLUSHER applications are FUSE daemons, SCSI device
 emulation daemons, and daemons that perform error handling like multipath
 path recovery applications.
+.\" prctl PR_GET_IO_FLUSHER
 .TP
 .B PR_GET_IO_FLUSHER (Since Linux 5.6)
 Return (as the function result) the IO_FLUSHER state of the caller.
-- 
2.1.4

Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation

[Michael Kerrisk (man-pages)]

Hi Dave,

On 5/12/20 6:36 PM, Dave Martin wrote:
> The prctl.2 source is unnecessarily hard to navigate, not least
> because prctl option flags are traditionally named PR_* and so look
> just like prctl names.
> 
> For each actual prctl, add a comment of the form
> 
> 	.\" prctl PR_FOO
> 
> to make it move obvious where each top-level prctl starts.
> 
> Of course, we could add some clever macros, but let's not confuse
> dumb parsers.

A patch like this, which makes sweeping changes across the page,
should be best placed at the end of a series, I think.
The reason is that if I fail to apply this patch (and I am a
little dubious about it), then probably the rest of the patches
in the series won't apply. (Furthermore, it also forced me to
apply patch 02 already, which I wanted to reflect on a little.)

That said, I'll apply it, so that the remaining patches
apply cleanly. I'll consider later whether to keep this
change. For example, I wonder if a visually distinctive 
source line that is always the same would be better than
these comments that repeat the PR_* names. For example, 
something like

.\" ==========================

I'll circle back to this later.

Thanks,

Michael


> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> ---
>  man2/prctl.2 | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 48 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 9736434..e5b2b4b 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -77,6 +77,7 @@ is called with a first argument describing what to do
>  arguments with a significance depending on the first one.
>  The first argument can be:
>  .\"
> +.\" prctl PR_CAP_AMBIENT
>  .TP
>  .BR PR_CAP_AMBIENT " (since Linux 4.3)"
>  .\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08
> @@ -130,6 +131,7 @@ library in the form of
>  .BR cap_set_ambient (3),
>  and
>  .BR cap_reset_ambient (3).
> +.\" prctl PR_CAPBSET_READ
>  .TP
>  .BR PR_CAPBSET_READ " (since Linux 2.6.25)"
>  Return (as the function result) 1 if the capability specified in
> @@ -152,6 +154,7 @@ A higher-level interface layered on top of this operation is provided in the
>  .BR libcap (3)
>  library in the form of
>  .BR cap_get_bound (3).
> +.\" prctl PR_CAPBSET_DROP
>  .TP
>  .BR PR_CAPBSET_DROP " (since Linux 2.6.25)"
>  If the calling thread has the
> @@ -178,6 +181,7 @@ A higher-level interface layered on top of this operation is provided in the
>  .BR libcap (3)
>  library in the form of
>  .BR cap_drop_bound (3).
> +.\" prctl PR_SET_CHILD_SUBREAPER
>  .TP
>  .BR PR_SET_CHILD_SUBREAPER " (since Linux 3.4)"
>  .\" commit ebec18a6d3aa1e7d84aab16225e87fd25170ec2b
> @@ -224,11 +228,13 @@ Some
>  frameworks (e.g.,
>  .BR systemd (1))
>  employ a subreaper process for similar reasons.
> +.\" prctl PR_GET_CHILD_SUBREAPER
>  .TP
>  .BR PR_GET_CHILD_SUBREAPER " (since Linux 3.4)"
>  Return the "child subreaper" setting of the caller,
>  in the location pointed to by
>  .IR "(int\ *) arg2" .
> +.\" prctl PR_SET_DUMPABLE
>  .TP
>  .BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
>  Set the state of the "dumpable" attribute,
> @@ -297,6 +303,7 @@ the ownership of files in the process's
>  .IR /proc/[pid]
>  directory is affected as described in
>  .BR proc (5).
> +.\" prctl PR_GET_DUMPABLE
>  .TP
>  .BR PR_GET_DUMPABLE " (since Linux 2.3.20)"
>  Return (as the function result) the current state of the calling
> @@ -304,6 +311,7 @@ process's dumpable attribute.
>  .\" Since Linux 2.6.13, the dumpable flag can have the value 2,
>  .\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
>  .\" flags has a nonzero value.  This was fixed in 2.6.14.
> +.\" prctl PR_SET_ENDIAN
>  .TP
>  .BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
>  Set the endian-ness of the calling process to the value given
> @@ -314,11 +322,13 @@ in \fIarg2\fP, which should be one of the following:
>  or
>  .B PR_ENDIAN_PPC_LITTLE
>  (PowerPC pseudo little endian).
> +.\" prctl PR_GET_ENDIAN
>  .TP
>  .BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
>  Return the endian-ness of the calling process,
>  in the location pointed to by
>  .IR "(int\ *) arg2" .
> +.\" prctl PR_SET_FP_MODE
>  .TP
>  .BR PR_SET_FP_MODE " (since Linux 4.0, only on MIPS)"
>  .\" commit 9791554b45a2acc28247f66a5fd5bbc212a6b8c8
> @@ -425,6 +435,7 @@ The arguments
>  and
>  .IR arg5
>  are ignored.
> +.\" prctl PR_GET_FP_MODE
>  .TP
>  .BR PR_GET_FP_MODE " (since Linux 4.0, only on MIPS)"
>  Return (as the function result)
> @@ -442,6 +453,7 @@ The arguments
>  and
>  .IR arg5
>  are ignored.
> +.\" prctl PR_SET_FPEMU
>  .TP
>  .BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
>  Set floating-point emulation control bits to \fIarg2\fP.
> @@ -452,11 +464,13 @@ to silently emulate floating-point operation accesses, or
>  to not emulate floating-point operations and send
>  .B SIGFPE
>  instead.
> +.\" prctl PR_GET_FPEMU
>  .TP
>  .BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
>  Return floating-point emulation control bits,
>  in the location pointed to by
>  .IR "(int\ *) arg2" .
> +.\" prctl PR_SET_FPEXC
>  .TP
>  .BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
>  Set floating-point exception mode to \fIarg2\fP.
> @@ -470,11 +484,13 @@ Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
>  \fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode,
>  \fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode,
>  \fBPR_FP_EXC_PRECISE\fP for precise exception mode.
> +.\" prctl PR_GET_FPEXC
>  .TP
>  .BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
>  Return floating-point exception mode,
>  in the location pointed to by
>  .IR "(int\ *) arg2" .
> +.\" prctl PR_SET_KEEPCAPS
>  .TP
>  .BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
>  Set the state of the calling thread's "keep capabilities" flag.
> @@ -485,6 +501,7 @@ must be either 0 (clear the flag)
>  or 1 (set the flag).
>  The "keep capabilities" value will be reset to 0 on subsequent calls to
>  .BR execve (2).
> +.\" prctl PR_GET_KEEPCAPS
>  .TP
>  .BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
>  Return (as the function result) the current state of the calling thread's
> @@ -492,6 +509,7 @@ Return (as the function result) the current state of the calling thread's
>  See
>  .BR capabilities (7)
>  for a description of this flag.
> +.\" prctl PR_MCE_KILL
>  .TP
>  .BR PR_MCE_KILL " (since Linux 2.6.32)"
>  Set the machine check memory corruption kill policy for the calling thread.
> @@ -532,6 +550,7 @@ The policy is inherited by children.
>  The remaining unused
>  .BR prctl ()
>  arguments must be zero for future compatibility.
> +.\" prctl PR_MCE_KILL_GET
>  .TP
>  .BR PR_MCE_KILL_GET " (since Linux 2.6.32)"
>  Return (as the function result)
> @@ -539,6 +558,7 @@ the current per-process machine check kill policy.
>  All unused
>  .BR prctl ()
>  arguments must be zero.
> +.\" prctl PR_SET_MM
>  .TP
>  .BR PR_SET_MM " (since Linux 3.3)"
>  .\" commit 028ee4be34a09a6d48bdf30ab991ae933a7bc036
> @@ -716,6 +736,7 @@ This feature is available only if the kernel is built with the
>  .BR CONFIG_CHECKPOINT_RESTORE
>  option enabled.
>  .RE
> +.\" prctl PR_MPX_ENABLE_MANAGEMENT
>  .TP
>  .BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19) "
>  .\" commit fe3d197f84319d3bce379a9c0dc17b1f48ad358c
> @@ -791,6 +812,7 @@ had been called.
>  .IP
>  For further information on Intel MPX, see the kernel source file
>  .IR Documentation/x86/intel_mpx.txt .
> +.\" prctl PR_SET_NAME
>  .TP
>  .BR PR_SET_NAME " (since Linux 2.6.9)"
>  Set the name of the calling thread,
> @@ -819,6 +841,7 @@ in the buffer pointed to by
>  .IR "(char\ *) arg2" .
>  The buffer should allow space for up to 16 bytes;
>  the returned string will be null-terminated.
> +.\" prctl PR_SET_NO_NEW_PRIVS
>  .TP
>  .BR PR_SET_NO_NEW_PRIVS " (since Linux 3.5)"
>  Set the calling thread's
> @@ -862,6 +885,7 @@ For more information, see the kernel source file
>  before Linux 4.13).
>  See also
>  .BR seccomp (2).
> +.\" prctl PR_GET_NO_NEW_PRIVS
>  .TP
>  .BR PR_GET_NO_NEW_PRIVS " (since Linux 3.5)"
>  Return (as the function result) the value of the
> @@ -873,6 +897,7 @@ behavior.
>  A value of 1 indicates
>  .BR execve (2)
>  will operate in the privilege-restricting mode described above.
> +.\" prctl PR_SET_PDEATHSIG
>  .TP
>  .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
>  Set the parent-death signal
> @@ -922,11 +947,13 @@ or a binary that has associated capabilities (see
>  .BR capabilities (7));
>  otherwise, this value is preserved across
>  .BR execve (2).
> +.\" prctl PR_GET_PDEATHSIG
>  .TP
>  .BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
>  Return the current value of the parent process death signal,
>  in the location pointed to by
>  .IR "(int\ *) arg2" .
> +.\" prctl PR_SET_PTRACER
>  .TP
>  .BR PR_SET_PTRACER " (since Linux 3.4)"
>  .\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
> @@ -959,6 +986,7 @@ For further information, see the kernel source file
>  (or
>  .IR Documentation/security/Yama.txt
>  before Linux 4.13).
> +.\" prctl PR_SET_SECCOMP
>  .TP
>  .BR PR_SET_SECCOMP " (since Linux 2.6.23)"
>  .\" See http://thread.gmane.org/gmane.linux.kernel/542632
> @@ -1035,6 +1063,7 @@ For further information, see the kernel source file
>  (or
>  .IR Documentation/prctl/seccomp_filter.txt
>  before Linux 4.13).
> +.\" prctl PR_GET_SECCOMP
>  .TP
>  .BR PR_GET_SECCOMP " (since Linux 2.6.23)"
>  Return (as the function result)
> @@ -1061,18 +1090,21 @@ field of the
>  file provides a method of obtaining the same information,
>  without the risk that the process is killed; see
>  .BR proc (5).
> +.\" prctl PR_SET_SECUREBITS
>  .TP
>  .BR PR_SET_SECUREBITS " (since Linux 2.6.26)"
>  Set the "securebits" flags of the calling thread to the value supplied in
>  .IR arg2 .
>  See
>  .BR capabilities (7).
> +.\" prctl PR_GET_SECUREBITS
>  .TP
>  .BR PR_GET_SECUREBITS " (since Linux 2.6.26)"
>  Return (as the function result)
>  the "securebits" flags of the calling thread.
>  See
>  .BR capabilities (7).
> +.\" prctl PR_GET_SPECULATION_CTRL
>  .TP
>  .BR PR_GET_SPECULATION_CTRL " (since Linux 4.17)"
>  Return (as the function result)
> @@ -1119,6 +1151,7 @@ and
>  .I arg5
>  arguments must be specified as 0; otherwise the call fails with the error
>  .BR EINVAL .
> +.\" prctl PR_SET_SPECULATION_CTRL
>  .TP
>  .BR PR_SET_SPECULATION_CTRL " (since Linux 4.17)"
>  .\" commit b617cfc858161140d69cc0b5cc211996b557a1c7
> @@ -1174,6 +1207,7 @@ call failing with the error
>  .BR ENXIO .
>  For further details, see the kernel source file
>  .IR Documentation/admin-guide/kernel-parameters.txt .
> +.\" prctl PR_SET_THP_DISABLE
>  .TP
>  .BR PR_SET_THP_DISABLE " (since Linux 3.15)"
>  .\" commit a0715cc22601e8830ace98366c0c2bd8da52af52
> @@ -1191,6 +1225,7 @@ The setting of the "THP disable" flag is inherited by a child created via
>  and is preserved across
>  .BR execve (2).
>  .\"
> +.\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
>  .BR PR_TASK_PERF_EVENTS_DISABLE " (since Linux 2.6.31)"
>  Disable all performance counters attached to the calling process,
> @@ -1207,6 +1242,7 @@ Originally called
>  renamed (retaining the same numerical value)
>  in Linux 2.6.32.
>  .\"
> +.\" prctl PR_TASK_PERF_EVENTS_ENABLE
>  .TP
>  .BR PR_TASK_PERF_EVENTS_ENABLE " (since Linux 2.6.31)"
>  The converse of
> @@ -1220,11 +1256,13 @@ renamed
>  .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
>  in Linux 2.6.32.
>  .\"
> +.\" prctl PR_GET_THP_DISABLE
>  .TP
>  .BR PR_GET_THP_DISABLE " (since Linux 3.15)"
>  Return (as the function result) the current setting of the "THP disable"
>  flag for the calling thread:
>  either 1, if the flag is set, or 0, if it is not.
> +.\" prctl PR_GET_TID_ADDRESS
>  .TP
>  .BR PR_GET_TID_ADDRESS " (since Linux 3.5)"
>  .\" commit 300f786b2683f8bb1ec0afb6e1851183a479c86d
> @@ -1246,6 +1284,7 @@ system call does not have a compat implementation for
>  the AMD64 x32 and MIPS n32 ABIs,
>  and the kernel writes out a pointer using the kernel's pointer size,
>  this operation expects a user-space buffer of 8 (not 4) bytes on these ABIs.
> +.\" prctl PR_SET_TIMERSLACK
>  .TP
>  .BR PR_SET_TIMERSLACK " (since Linux 2.6.28)"
>  .\" See https://lwn.net/Articles/369549/
> @@ -1316,10 +1355,12 @@ can be examined and changed via the file
>  .IR /proc/[pid]/timerslack_ns .
>  See
>  .BR proc (5).
> +.\" prctl PR_GET_TIMERSLACK
>  .TP
>  .BR PR_GET_TIMERSLACK " (since Linux 2.6.28)"
>  Return (as the function result)
>  the "current" timer slack value of the calling thread.
> +.\" prctl PR_SET_TIMING
>  .TP
>  .BR PR_SET_TIMING " (since Linux 2.6.0)"
>  .\" Precisely: Linux 2.6.0-test4
> @@ -1338,11 +1379,13 @@ is not currently implemented
>  .\" PR_TIMING_TIMESTAMP doesn't do anything in 2.6.26-rc8,
>  .\" and looking at the patch history, it appears
>  .\" that it never did anything.
> +.\" prctl PR_GET_TIMING
>  .TP
>  .BR PR_GET_TIMING " (since Linux 2.6.0)"
>  .\" Precisely: Linux 2.6.0-test4
>  Return (as the function result) which process timing method is currently
>  in use.
> +.\" prctl PR_SET_TSC
>  .TP
>  .BR PR_SET_TSC " (since Linux 2.6.26, x86 only)"
>  Set the state of the flag determining whether the timestamp counter
> @@ -1356,12 +1399,14 @@ to allow it to be read, or
>  to generate a
>  .B SIGSEGV
>  when the process tries to read the timestamp counter.
> +.\" prctl PR_GET_TSC
>  .TP
>  .BR PR_GET_TSC " (since Linux 2.6.26, x86 only)"
>  Return the state of the flag determining whether the timestamp counter
>  can be read,
>  in the location pointed to by
>  .IR "(int\ *) arg2" .
> +.\" prctl PR_SET_UNALIGN
>  .TP
>  .B PR_SET_UNALIGN
>  (Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15;
> @@ -1385,6 +1430,7 @@ flag in
>  operation of the
>  .BR setsysinfo ()
>  system call on Tru64).
> +.\" prctl PR_GET_UNALIGN
>  .TP
>  .B PR_GET_UNALIGN
>  (See
> @@ -1392,6 +1438,7 @@ system call on Tru64).
>  for information on versions and architectures.)
>  Return unaligned access control bits, in the location pointed to by
>  .IR "(unsigned int\ *) arg2" .
> +.\" prctl PR_SET_IO_FLUSHER
>  .TP
>  .BR PR_SET_IO_FLUSHER " (since Linux 5.6)"
>  If a user process is involved in the block layer or filesystem I/O path,
> @@ -1420,6 +1467,7 @@ and is preserved across
>  Examples of IO_FLUSHER applications are FUSE daemons, SCSI device
>  emulation daemons, and daemons that perform error handling like multipath
>  path recovery applications.
> +.\" prctl PR_GET_IO_FLUSHER
>  .TP
>  .B PR_GET_IO_FLUSHER (Since Linux 5.6)
>  Return (as the function result) the IO_FLUSHER state of the caller.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation

[Dave Martin]

On Wed, May 13, 2020 at 12:09:27PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
> 
> On 5/12/20 6:36 PM, Dave Martin wrote:
> > The prctl.2 source is unnecessarily hard to navigate, not least
> > because prctl option flags are traditionally named PR_* and so look
> > just like prctl names.
> > 
> > For each actual prctl, add a comment of the form
> > 
> > 	.\" prctl PR_FOO
> > 
> > to make it move obvious where each top-level prctl starts.
> > 
> > Of course, we could add some clever macros, but let's not confuse
> > dumb parsers.
> 
> A patch like this, which makes sweeping changes across the page,
> should be best placed at the end of a series, I think.
> The reason is that if I fail to apply this patch (and I am a
> little dubious about it), then probably the rest of the patches
> in the series won't apply. (Furthermore, it also forced me to
> apply patch 02 already, which I wanted to reflect on a little.)

Agreed, I'll try to do that in future.

> That said, I'll apply it, so that the remaining patches
> apply cleanly. I'll consider later whether to keep this
> change. For example, I wonder if a visually distinctive 
> source line that is always the same would be better than
> these comments that repeat the PR_* names. For example, 
> something like
> 
> .\" ==========================
> 
> I'll circle back to this later.

I'd prefer to keep the name if we can, since navigating by search is
otherwise bothersome due to false hits.

Could we do both, say:

.\" === PR_FOO ===

If you prefer to reject this patch, I'm happy to rebase and repost the
series as appropriate.

In any case, this one is nice to have rather than essential.

Cheers
---Dave

Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation

[Michael Kerrisk (man-pages)]

Hi Dave,

On 5/13/20 12:56 PM, Dave Martin wrote:
> On Wed, May 13, 2020 at 12:09:27PM +0200, Michael Kerrisk (man-pages) wrote:
>> Hi Dave,
>>
>> On 5/12/20 6:36 PM, Dave Martin wrote:
>>> The prctl.2 source is unnecessarily hard to navigate, not least
>>> because prctl option flags are traditionally named PR_* and so look
>>> just like prctl names.
>>>
>>> For each actual prctl, add a comment of the form
>>>
>>> 	.\" prctl PR_FOO
>>>
>>> to make it move obvious where each top-level prctl starts.
>>>
>>> Of course, we could add some clever macros, but let's not confuse
>>> dumb parsers.
>>
>> A patch like this, which makes sweeping changes across the page,
>> should be best placed at the end of a series, I think.
>> The reason is that if I fail to apply this patch (and I am a
>> little dubious about it), then probably the rest of the patches
>> in the series won't apply. (Furthermore, it also forced me to
>> apply patch 02 already, which I wanted to reflect on a little.)
> 
> Agreed, I'll try to do that in future.
> 
>> That said, I'll apply it, so that the remaining patches
>> apply cleanly. I'll consider later whether to keep this
>> change. For example, I wonder if a visually distinctive 
>> source line that is always the same would be better than
>> these comments that repeat the PR_* names. For example, 
>> something like
>>
>> .\" ==========================
>>
>> I'll circle back to this later.
> 
> I'd prefer to keep the name if we can, since navigating by search is
> otherwise bothersome due to false hits.
> 
> Could we do both, say:
> 
> .\" === PR_FOO ===

Okay -- I'll give that some thought.

> If you prefer to reject this patch, I'm happy to rebase and repost the
> series as appropriate.
> 
> In any case, this one is nice to have rather than essential.

For now, the patch is already committed and pushed.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation

[Dave Martin]

On Wed, May 13, 2020 at 01:03:27PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
> 
> On 5/13/20 12:56 PM, Dave Martin wrote:
> > On Wed, May 13, 2020 at 12:09:27PM +0200, Michael Kerrisk (man-pages) wrote:
> >> Hi Dave,
> >>
> >> On 5/12/20 6:36 PM, Dave Martin wrote:
> >>> The prctl.2 source is unnecessarily hard to navigate, not least
> >>> because prctl option flags are traditionally named PR_* and so look
> >>> just like prctl names.
> >>>
> >>> For each actual prctl, add a comment of the form
> >>>
> >>> 	.\" prctl PR_FOO
> >>>
> >>> to make it move obvious where each top-level prctl starts.
> >>>
> >>> Of course, we could add some clever macros, but let's not confuse
> >>> dumb parsers.
> >>
> >> A patch like this, which makes sweeping changes across the page,
> >> should be best placed at the end of a series, I think.
> >> The reason is that if I fail to apply this patch (and I am a
> >> little dubious about it), then probably the rest of the patches
> >> in the series won't apply. (Furthermore, it also forced me to
> >> apply patch 02 already, which I wanted to reflect on a little.)
> > 
> > Agreed, I'll try to do that in future.
> > 
> >> That said, I'll apply it, so that the remaining patches
> >> apply cleanly. I'll consider later whether to keep this
> >> change. For example, I wonder if a visually distinctive 
> >> source line that is always the same would be better than
> >> these comments that repeat the PR_* names. For example, 
> >> something like
> >>
> >> .\" ==========================
> >>
> >> I'll circle back to this later.
> > 
> > I'd prefer to keep the name if we can, since navigating by search is
> > otherwise bothersome due to false hits.
> > 
> > Could we do both, say:
> > 
> > .\" === PR_FOO ===
> 
> Okay -- I'll give that some thought.
> 
> > If you prefer to reject this patch, I'm happy to rebase and repost the
> > series as appropriate.
> > 
> > In any case, this one is nice to have rather than essential.
> 
> For now, the patch is already committed and pushed.

OK, thanks.  I'm happy to write a further patch when you've decided what
to do, if it saves you work.

Cheers
---Dave

Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation

[Michael Kerrisk (man-pages)]

Hi Dave,

On 5/13/20 1:15 PM, Dave Martin wrote:
> On Wed, May 13, 2020 at 01:03:27PM +0200, Michael Kerrisk (man-pages) wrote:
>> Hi Dave,
>>
>> On 5/13/20 12:56 PM, Dave Martin wrote:
>>> On Wed, May 13, 2020 at 12:09:27PM +0200, Michael Kerrisk (man-pages) wrote:
>>>> Hi Dave,
>>>>
>>>> On 5/12/20 6:36 PM, Dave Martin wrote:
>>>>> The prctl.2 source is unnecessarily hard to navigate, not least
>>>>> because prctl option flags are traditionally named PR_* and so look
>>>>> just like prctl names.
>>>>>
>>>>> For each actual prctl, add a comment of the form
>>>>>
>>>>> 	.\" prctl PR_FOO
>>>>>
>>>>> to make it move obvious where each top-level prctl starts.
>>>>>
>>>>> Of course, we could add some clever macros, but let's not confuse
>>>>> dumb parsers.
>>>>
>>>> A patch like this, which makes sweeping changes across the page,
>>>> should be best placed at the end of a series, I think.
>>>> The reason is that if I fail to apply this patch (and I am a
>>>> little dubious about it), then probably the rest of the patches
>>>> in the series won't apply. (Furthermore, it also forced me to
>>>> apply patch 02 already, which I wanted to reflect on a little.)
>>>
>>> Agreed, I'll try to do that in future.
>>>
>>>> That said, I'll apply it, so that the remaining patches
>>>> apply cleanly. I'll consider later whether to keep this
>>>> change. For example, I wonder if a visually distinctive 
>>>> source line that is always the same would be better than
>>>> these comments that repeat the PR_* names. For example, 
>>>> something like
>>>>
>>>> .\" ==========================
>>>>
>>>> I'll circle back to this later.
>>>
>>> I'd prefer to keep the name if we can, since navigating by search is
>>> otherwise bothersome due to false hits.
>>>
>>> Could we do both, say:
>>>
>>> .\" === PR_FOO ===
>>
>> Okay -- I'll give that some thought.
>>
>>> If you prefer to reject this patch, I'm happy to rebase and repost the
>>> series as appropriate.
>>>
>>> In any case, this one is nice to have rather than essential.
>>
>> For now, the patch is already committed and pushed.
> 
> OK, thanks.  I'm happy to write a further patch when you've decided what
> to do, if it saves you work.

Let's leave this for the moment. Once the dust settles on your 
remaining patches, I'll try to remember to circle back on this.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation

[Dave Martin]

On Wed, May 13, 2020 at 01:48:36PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
> 
> On 5/13/20 1:15 PM, Dave Martin wrote:
> > On Wed, May 13, 2020 at 01:03:27PM +0200, Michael Kerrisk (man-pages) wrote:
> >> Hi Dave,
> >>
> >> On 5/13/20 12:56 PM, Dave Martin wrote:
> >>> On Wed, May 13, 2020 at 12:09:27PM +0200, Michael Kerrisk (man-pages) wrote:
> >>>> Hi Dave,
> >>>>
> >>>> On 5/12/20 6:36 PM, Dave Martin wrote:
> >>>>> The prctl.2 source is unnecessarily hard to navigate, not least
> >>>>> because prctl option flags are traditionally named PR_* and so look
> >>>>> just like prctl names.
> >>>>>
> >>>>> For each actual prctl, add a comment of the form
> >>>>>
> >>>>> 	.\" prctl PR_FOO
> >>>>>
> >>>>> to make it move obvious where each top-level prctl starts.
> >>>>>
> >>>>> Of course, we could add some clever macros, but let's not confuse
> >>>>> dumb parsers.
> >>>>
> >>>> A patch like this, which makes sweeping changes across the page,
> >>>> should be best placed at the end of a series, I think.
> >>>> The reason is that if I fail to apply this patch (and I am a
> >>>> little dubious about it), then probably the rest of the patches
> >>>> in the series won't apply. (Furthermore, it also forced me to
> >>>> apply patch 02 already, which I wanted to reflect on a little.)
> >>>
> >>> Agreed, I'll try to do that in future.
> >>>
> >>>> That said, I'll apply it, so that the remaining patches
> >>>> apply cleanly. I'll consider later whether to keep this
> >>>> change. For example, I wonder if a visually distinctive 
> >>>> source line that is always the same would be better than
> >>>> these comments that repeat the PR_* names. For example, 
> >>>> something like
> >>>>
> >>>> .\" ==========================
> >>>>
> >>>> I'll circle back to this later.
> >>>
> >>> I'd prefer to keep the name if we can, since navigating by search is
> >>> otherwise bothersome due to false hits.
> >>>
> >>> Could we do both, say:
> >>>
> >>> .\" === PR_FOO ===
> >>
> >> Okay -- I'll give that some thought.
> >>
> >>> If you prefer to reject this patch, I'm happy to rebase and repost the
> >>> series as appropriate.
> >>>
> >>> In any case, this one is nice to have rather than essential.
> >>
> >> For now, the patch is already committed and pushed.
> > 
> > OK, thanks.  I'm happy to write a further patch when you've decided what
> > to do, if it saves you work.
> 
> Let's leave this for the moment. Once the dust settles on your 
> remaining patches, I'll try to remember to circle back on this.

OK, give me a should if you need anything from me.

Cheers
---Dave

[PATCH 05/14] prctl.2: tfix listing order of prctls

[Dave Martin]

The prctl list has historically been sorted by prctl name (ignoring
any SET_ or GET_ prefix) to make individual prctls easier to find.
Some noise seems to have crept in since.

Sort the list back into order.  Similarly, reorder the list of
prctls specified to return non-zero values on success.

Content movement only.  No semantic change.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
---
 man2/prctl.2 | 138 +++++++++++++++++++++++++++++------------------------------
 1 file changed, 69 insertions(+), 69 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index e5b2b4b..1611448 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -490,6 +490,52 @@ Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
 Return floating-point exception mode,
 in the location pointed to by
 .IR "(int\ *) arg2" .
+.\" prctl PR_SET_IO_FLUSHER
+.TP
+.BR PR_SET_IO_FLUSHER " (since Linux 5.6)"
+If a user process is involved in the block layer or filesystem I/O path,
+and can allocate memory while processing I/O requests it must set
+\fIarg2\fP to 1.
+This will put the process in the IO_FLUSHER state,
+which allows it special treatment to make progress when allocating memory.
+If \fIarg2\fP is 0, the process will clear the IO_FLUSHER state, and
+the default behavior will be used.
+.IP
+The calling process must have the
+.BR CAP_SYS_RESOURCE
+capability.
+.IP
+.IR arg3 ,
+.IR arg4 ,
+and
+.IR arg5
+must be zero.
+.IP
+The IO_FLUSHER state is inherited by a child process created via
+.BR fork (2)
+and is preserved across
+.BR execve (2).
+.IP
+Examples of IO_FLUSHER applications are FUSE daemons, SCSI device
+emulation daemons, and daemons that perform error handling like multipath
+path recovery applications.
+.\" prctl PR_GET_IO_FLUSHER
+.TP
+.B PR_GET_IO_FLUSHER (Since Linux 5.6)
+Return (as the function result) the IO_FLUSHER state of the caller.
+A value of 1 indicates that the caller is in the IO_FLUSHER state;
+0 indicates that the caller is not in the IO_FLUSHER state.
+.IP
+The calling process must have the
+.BR CAP_SYS_RESOURCE
+capability.
+.IP
+.IR arg2 ,
+.IR arg3 ,
+.IR arg4 ,
+and
+.IR arg5
+must be zero.
 .\" prctl PR_SET_KEEPCAPS
 .TP
 .BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
@@ -1207,23 +1253,6 @@ call failing with the error
 .BR ENXIO .
 For further details, see the kernel source file
 .IR Documentation/admin-guide/kernel-parameters.txt .
-.\" prctl PR_SET_THP_DISABLE
-.TP
-.BR PR_SET_THP_DISABLE " (since Linux 3.15)"
-.\" commit a0715cc22601e8830ace98366c0c2bd8da52af52
-Set the state of the "THP disable" flag for the calling thread.
-If
-.I arg2
-has a nonzero value, the flag is set, otherwise it is cleared.
-Setting this flag provides a method
-for disabling transparent huge pages
-for jobs where the code cannot be modified, and using a malloc hook with
-.BR madvise (2)
-is not an option (i.e., statically allocated data).
-The setting of the "THP disable" flag is inherited by a child created via
-.BR fork (2)
-and is preserved across
-.BR execve (2).
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1256,6 +1285,23 @@ renamed
 .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
 in Linux 2.6.32.
 .\"
+.\" prctl PR_SET_THP_DISABLE
+.TP
+.BR PR_SET_THP_DISABLE " (since Linux 3.15)"
+.\" commit a0715cc22601e8830ace98366c0c2bd8da52af52
+Set the state of the "THP disable" flag for the calling thread.
+If
+.I arg2
+has a nonzero value, the flag is set, otherwise it is cleared.
+Setting this flag provides a method
+for disabling transparent huge pages
+for jobs where the code cannot be modified, and using a malloc hook with
+.BR madvise (2)
+is not an option (i.e., statically allocated data).
+The setting of the "THP disable" flag is inherited by a child created via
+.BR fork (2)
+and is preserved across
+.BR execve (2).
 .\" prctl PR_GET_THP_DISABLE
 .TP
 .BR PR_GET_THP_DISABLE " (since Linux 3.15)"
@@ -1438,67 +1484,21 @@ system call on Tru64).
 for information on versions and architectures.)
 Return unaligned access control bits, in the location pointed to by
 .IR "(unsigned int\ *) arg2" .
-.\" prctl PR_SET_IO_FLUSHER
-.TP
-.BR PR_SET_IO_FLUSHER " (since Linux 5.6)"
-If a user process is involved in the block layer or filesystem I/O path,
-and can allocate memory while processing I/O requests it must set
-\fIarg2\fP to 1.
-This will put the process in the IO_FLUSHER state,
-which allows it special treatment to make progress when allocating memory.
-If \fIarg2\fP is 0, the process will clear the IO_FLUSHER state, and
-the default behavior will be used.
-.IP
-The calling process must have the
-.BR CAP_SYS_RESOURCE
-capability.
-.IP
-.IR arg3 ,
-.IR arg4 ,
-and
-.IR arg5
-must be zero.
-.IP
-The IO_FLUSHER state is inherited by a child process created via
-.BR fork (2)
-and is preserved across
-.BR execve (2).
-.IP
-Examples of IO_FLUSHER applications are FUSE daemons, SCSI device
-emulation daemons, and daemons that perform error handling like multipath
-path recovery applications.
-.\" prctl PR_GET_IO_FLUSHER
-.TP
-.B PR_GET_IO_FLUSHER (Since Linux 5.6)
-Return (as the function result) the IO_FLUSHER state of the caller.
-A value of 1 indicates that the caller is in the IO_FLUSHER state;
-0 indicates that the caller is not in the IO_FLUSHER state.
-.IP
-The calling process must have the
-.BR CAP_SYS_RESOURCE
-capability.
-.IP
-.IR arg2 ,
-.IR arg3 ,
-.IR arg4 ,
-and
-.IR arg5
-must be zero.
 .SH RETURN VALUE
 On success,
+.BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET ,
+.BR PR_CAPBSET_READ ,
 .BR PR_GET_DUMPABLE ,
 .BR PR_GET_FP_MODE ,
+.BR PR_GET_IO_FLUSHER ,
 .BR PR_GET_KEEPCAPS ,
+.BR PR_MCE_KILL_GET ,
 .BR PR_GET_NO_NEW_PRIVS ,
+.BR PR_GET_SECUREBITS ,
+.BR PR_GET_SPECULATION_CTRL ,
 .BR PR_GET_THP_DISABLE ,
-.BR PR_CAPBSET_READ ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
-.BR PR_GET_SECUREBITS ,
-.BR PR_GET_SPECULATION_CTRL ,
-.BR PR_MCE_KILL_GET ,
-.BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET ,
-.BR PR_GET_IO_FLUSHER ,
 and (if it returns)
 .BR PR_GET_SECCOMP
 return the nonnegative values described above.
-- 
2.1.4

Re: [PATCH 05/14] prctl.2: tfix listing order of prctls

[Michael Kerrisk (man-pages)]

Hi Dave,

On 5/12/20 6:36 PM, Dave Martin wrote:
> The prctl list has historically been sorted by prctl name (ignoring
> any SET_ or GET_ prefix) to make individual prctls easier to find.
> Some noise seems to have crept in since.
> 
> Sort the list back into order.  Similarly, reorder the list of
> prctls specified to return non-zero values on success.

This is a good patch. But see my comments on patch 04.
I'd prefer a patch like this at the end of a series, 
rather than in the middle of it.

> Content movement only.  No semantic change.

And explicitly noting that detail is very helpful to me.

Patch applied.

Cheers,

Michael

> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> ---
>  man2/prctl.2 | 138 +++++++++++++++++++++++++++++------------------------------
>  1 file changed, 69 insertions(+), 69 deletions(-)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index e5b2b4b..1611448 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -490,6 +490,52 @@ Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
>  Return floating-point exception mode,
>  in the location pointed to by
>  .IR "(int\ *) arg2" .
> +.\" prctl PR_SET_IO_FLUSHER
> +.TP
> +.BR PR_SET_IO_FLUSHER " (since Linux 5.6)"
> +If a user process is involved in the block layer or filesystem I/O path,
> +and can allocate memory while processing I/O requests it must set
> +\fIarg2\fP to 1.
> +This will put the process in the IO_FLUSHER state,
> +which allows it special treatment to make progress when allocating memory.
> +If \fIarg2\fP is 0, the process will clear the IO_FLUSHER state, and
> +the default behavior will be used.
> +.IP
> +The calling process must have the
> +.BR CAP_SYS_RESOURCE
> +capability.
> +.IP
> +.IR arg3 ,
> +.IR arg4 ,
> +and
> +.IR arg5
> +must be zero.
> +.IP
> +The IO_FLUSHER state is inherited by a child process created via
> +.BR fork (2)
> +and is preserved across
> +.BR execve (2).
> +.IP
> +Examples of IO_FLUSHER applications are FUSE daemons, SCSI device
> +emulation daemons, and daemons that perform error handling like multipath
> +path recovery applications.
> +.\" prctl PR_GET_IO_FLUSHER
> +.TP
> +.B PR_GET_IO_FLUSHER (Since Linux 5.6)
> +Return (as the function result) the IO_FLUSHER state of the caller.
> +A value of 1 indicates that the caller is in the IO_FLUSHER state;
> +0 indicates that the caller is not in the IO_FLUSHER state.
> +.IP
> +The calling process must have the
> +.BR CAP_SYS_RESOURCE
> +capability.
> +.IP
> +.IR arg2 ,
> +.IR arg3 ,
> +.IR arg4 ,
> +and
> +.IR arg5
> +must be zero.
>  .\" prctl PR_SET_KEEPCAPS
>  .TP
>  .BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
> @@ -1207,23 +1253,6 @@ call failing with the error
>  .BR ENXIO .
>  For further details, see the kernel source file
>  .IR Documentation/admin-guide/kernel-parameters.txt .
> -.\" prctl PR_SET_THP_DISABLE
> -.TP
> -.BR PR_SET_THP_DISABLE " (since Linux 3.15)"
> -.\" commit a0715cc22601e8830ace98366c0c2bd8da52af52
> -Set the state of the "THP disable" flag for the calling thread.
> -If
> -.I arg2
> -has a nonzero value, the flag is set, otherwise it is cleared.
> -Setting this flag provides a method
> -for disabling transparent huge pages
> -for jobs where the code cannot be modified, and using a malloc hook with
> -.BR madvise (2)
> -is not an option (i.e., statically allocated data).
> -The setting of the "THP disable" flag is inherited by a child created via
> -.BR fork (2)
> -and is preserved across
> -.BR execve (2).
>  .\"
>  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
> @@ -1256,6 +1285,23 @@ renamed
>  .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
>  in Linux 2.6.32.
>  .\"
> +.\" prctl PR_SET_THP_DISABLE
> +.TP
> +.BR PR_SET_THP_DISABLE " (since Linux 3.15)"
> +.\" commit a0715cc22601e8830ace98366c0c2bd8da52af52
> +Set the state of the "THP disable" flag for the calling thread.
> +If
> +.I arg2
> +has a nonzero value, the flag is set, otherwise it is cleared.
> +Setting this flag provides a method
> +for disabling transparent huge pages
> +for jobs where the code cannot be modified, and using a malloc hook with
> +.BR madvise (2)
> +is not an option (i.e., statically allocated data).
> +The setting of the "THP disable" flag is inherited by a child created via
> +.BR fork (2)
> +and is preserved across
> +.BR execve (2).
>  .\" prctl PR_GET_THP_DISABLE
>  .TP
>  .BR PR_GET_THP_DISABLE " (since Linux 3.15)"
> @@ -1438,67 +1484,21 @@ system call on Tru64).
>  for information on versions and architectures.)
>  Return unaligned access control bits, in the location pointed to by
>  .IR "(unsigned int\ *) arg2" .
> -.\" prctl PR_SET_IO_FLUSHER
> -.TP
> -.BR PR_SET_IO_FLUSHER " (since Linux 5.6)"
> -If a user process is involved in the block layer or filesystem I/O path,
> -and can allocate memory while processing I/O requests it must set
> -\fIarg2\fP to 1.
> -This will put the process in the IO_FLUSHER state,
> -which allows it special treatment to make progress when allocating memory.
> -If \fIarg2\fP is 0, the process will clear the IO_FLUSHER state, and
> -the default behavior will be used.
> -.IP
> -The calling process must have the
> -.BR CAP_SYS_RESOURCE
> -capability.
> -.IP
> -.IR arg3 ,
> -.IR arg4 ,
> -and
> -.IR arg5
> -must be zero.
> -.IP
> -The IO_FLUSHER state is inherited by a child process created via
> -.BR fork (2)
> -and is preserved across
> -.BR execve (2).
> -.IP
> -Examples of IO_FLUSHER applications are FUSE daemons, SCSI device
> -emulation daemons, and daemons that perform error handling like multipath
> -path recovery applications.
> -.\" prctl PR_GET_IO_FLUSHER
> -.TP
> -.B PR_GET_IO_FLUSHER (Since Linux 5.6)
> -Return (as the function result) the IO_FLUSHER state of the caller.
> -A value of 1 indicates that the caller is in the IO_FLUSHER state;
> -0 indicates that the caller is not in the IO_FLUSHER state.
> -.IP
> -The calling process must have the
> -.BR CAP_SYS_RESOURCE
> -capability.
> -.IP
> -.IR arg2 ,
> -.IR arg3 ,
> -.IR arg4 ,
> -and
> -.IR arg5
> -must be zero.
>  .SH RETURN VALUE
>  On success,
> +.BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET ,
> +.BR PR_CAPBSET_READ ,
>  .BR PR_GET_DUMPABLE ,
>  .BR PR_GET_FP_MODE ,
> +.BR PR_GET_IO_FLUSHER ,
>  .BR PR_GET_KEEPCAPS ,
> +.BR PR_MCE_KILL_GET ,
>  .BR PR_GET_NO_NEW_PRIVS ,
> +.BR PR_GET_SECUREBITS ,
> +.BR PR_GET_SPECULATION_CTRL ,
>  .BR PR_GET_THP_DISABLE ,
> -.BR PR_CAPBSET_READ ,
>  .BR PR_GET_TIMING ,
>  .BR PR_GET_TIMERSLACK ,
> -.BR PR_GET_SECUREBITS ,
> -.BR PR_GET_SPECULATION_CTRL ,
> -.BR PR_MCE_KILL_GET ,
> -.BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET ,
> -.BR PR_GET_IO_FLUSHER ,
>  and (if it returns)
>  .BR PR_GET_SECCOMP
>  return the nonnegative values described above.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 05/14] prctl.2: tfix listing order of prctls

[Dave Martin]

On Wed, May 13, 2020 at 12:10:53PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
> 
> On 5/12/20 6:36 PM, Dave Martin wrote:
> > The prctl list has historically been sorted by prctl name (ignoring
> > any SET_ or GET_ prefix) to make individual prctls easier to find.
> > Some noise seems to have crept in since.
> > 
> > Sort the list back into order.  Similarly, reorder the list of
> > prctls specified to return non-zero values on success.
> 
> This is a good patch. But see my comments on patch 04.
> I'd prefer a patch like this at the end of a series, 
> rather than in the middle of it.

Ack.

Ideally we could check the order with a script, but that seemed a step
too far.

What's the view on having parts of the man pages generated, rather then
being distributed ready-built?

If we split prctl.2 up with a fragment per prctl, we could paste the
fragments together in the right order with a script.

> 
> > Content movement only.  No semantic change.
> 
> And explicitly noting that detail is very helpful to me.

Unless of course I'm lying ;)  (I'm not, but I won't be offended if you
check.)

Cheers
---Dave

Re: [PATCH 05/14] prctl.2: tfix listing order of prctls

[Michael Kerrisk (man-pages)]

Hi Dave,

On 5/13/20 1:21 PM, Dave Martin wrote:
> On Wed, May 13, 2020 at 12:10:53PM +0200, Michael Kerrisk (man-pages) wrote:
>> Hi Dave,
>>
>> On 5/12/20 6:36 PM, Dave Martin wrote:
>>> The prctl list has historically been sorted by prctl name (ignoring
>>> any SET_ or GET_ prefix) to make individual prctls easier to find.
>>> Some noise seems to have crept in since.
>>>
>>> Sort the list back into order.  Similarly, reorder the list of
>>> prctls specified to return non-zero values on success.
>>
>> This is a good patch. But see my comments on patch 04.
>> I'd prefer a patch like this at the end of a series, 
>> rather than in the middle of it.
> 
> Ack.
> 
> Ideally we could check the order with a script, but that seemed a step
> too far.

Quite.

> What's the view on having parts of the man pages generated, rather then
> being distributed ready-built?

I'm not keen (until someone shows me compelling benefits). Splitting
things up would make pages harder to edit, and IMO increase
the chance for inconsistencies in pages.

> If we split prctl.2 up with a fragment per prctl, we could paste the
> fragments together in the right order with a script.
> 
>>
>>> Content movement only.  No semantic change.
>>
>> And explicitly noting that detail is very helpful to me.
> 
> Unless of course I'm lying ;)  (I'm not, but I won't be offended if you
> check.)

Actually, with your first two patches, you impressed right out of
the gate, so my "I'm gonna blindly trust this guy" needle already
switched up pretty high :-).

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 05/14] prctl.2: tfix listing order of prctls

[Dave Martin]

On Wed, May 13, 2020 at 01:31:32PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
> 
> On 5/13/20 1:21 PM, Dave Martin wrote:
> > On Wed, May 13, 2020 at 12:10:53PM +0200, Michael Kerrisk (man-pages) wrote:
> >> Hi Dave,
> >>
> >> On 5/12/20 6:36 PM, Dave Martin wrote:
> >>> The prctl list has historically been sorted by prctl name (ignoring
> >>> any SET_ or GET_ prefix) to make individual prctls easier to find.
> >>> Some noise seems to have crept in since.
> >>>
> >>> Sort the list back into order.  Similarly, reorder the list of
> >>> prctls specified to return non-zero values on success.
> >>
> >> This is a good patch. But see my comments on patch 04.
> >> I'd prefer a patch like this at the end of a series, 
> >> rather than in the middle of it.
> > 
> > Ack.
> > 
> > Ideally we could check the order with a script, but that seemed a step
> > too far.
> 
> Quite.
> 
> > What's the view on having parts of the man pages generated, rather then
> > being distributed ready-built?
> 
> I'm not keen (until someone shows me compelling benefits). Splitting
> things up would make pages harder to edit, and IMO increase
> the chance for inconsistencies in pages.

Fair enough.  I might experiment with something, but I won't expect an
easy sell!

This sort of thing was part of my motivation for having a distinctive
marker for the start of each prctl entry.

> 
> > If we split prctl.2 up with a fragment per prctl, we could paste the
> > fragments together in the right order with a script.
> > 
> >>
> >>> Content movement only.  No semantic change.
> >>
> >> And explicitly noting that detail is very helpful to me.
> > 
> > Unless of course I'm lying ;)  (I'm not, but I won't be offended if you
> > check.)
> 
> Actually, with your first two patches, you impressed right out of
> the gate, so my "I'm gonna blindly trust this guy" needle already
> switched up pretty high :-).

I guess I'll need to be careful...

Cheers
---Dave

[PATCH 06/14] prctl.2: ffix quotation mark tweaks

[Dave Martin]

Convert quote marks used for information terms in prose to use
\(oq .. \(cq, for better graphical rendering.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>

---

Note, this can lead to misrendering on badly-configured systems.
However, many man pages do it.

In the C locale (or with -Tascii) the quotes still render as ' .
---
 man2/prctl.2 | 71 ++++++++++++++++++++++++++++++------------------------------
 1 file changed, 36 insertions(+), 35 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 1611448..7a3fc5c 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -188,7 +188,7 @@ library in the form of
 If
 .I arg2
 is nonzero,
-set the "child subreaper" attribute of the calling process;
+set the \(oqchild subreaper\(cq attribute of the calling process;
 if
 .I arg2
 is zero, unset the attribute.
@@ -210,7 +210,7 @@ signal and will be able to
 .BR wait (2)
 on the process to discover its termination status.
 .IP
-The setting of the "child subreaper" attribute
+The setting of the \(oqchild subreaper\(cq attribute
 is not inherited by children created by
 .BR fork (2)
 and
@@ -231,13 +231,13 @@ employ a subreaper process for similar reasons.
 .\" prctl PR_GET_CHILD_SUBREAPER
 .TP
 .BR PR_GET_CHILD_SUBREAPER " (since Linux 3.4)"
-Return the "child subreaper" setting of the caller,
+Return the \(oqchild subreaper\(cq setting of the caller,
 in the location pointed to by
 .IR "(int\ *) arg2" .
 .\" prctl PR_SET_DUMPABLE
 .TP
 .BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
-Set the state of the "dumpable" attribute,
+Set the state of the \(oqdumpable\(cq attribute,
 which determines whether core dumps are produced for the calling process
 upon delivery of a signal whose default behavior is to produce a core dump.
 .IP
@@ -263,7 +263,7 @@ for security reasons, this feature has been removed.
 in
 .BR proc (5).)
 .IP
-Normally, the "dumpable" attribue is set to 1.
+Normally, the \(oqdumpable\(cq attribue is set to 1.
 However, it is reset to the current value contained in the file
 .IR /proc/sys/fs/\:suid_dumpable
 (which by default has the value 0),
@@ -539,19 +539,19 @@ must be zero.
 .\" prctl PR_SET_KEEPCAPS
 .TP
 .BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
-Set the state of the calling thread's "keep capabilities" flag.
+Set the state of the calling thread's \(oqkeep capabilities\(cq flag.
 The effect of this flag is described in
 .BR capabilities (7).
 .I arg2
 must be either 0 (clear the flag)
 or 1 (set the flag).
-The "keep capabilities" value will be reset to 0 on subsequent calls to
+The \(oqkeep capabilities\(cq value will be reset to 0 on subsequent calls to
 .BR execve (2).
 .\" prctl PR_GET_KEEPCAPS
 .TP
 .BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
 Return (as the function result) the current state of the calling thread's
-"keep capabilities" flag.
+\(oqkeep capabilities\(cq flag.
 See
 .BR capabilities (7)
 for a description of this flag.
@@ -806,8 +806,8 @@ and a set of special instruction prefixes that tell the CPU on which
 instructions it should do bounds enforcement.
 There is a limited number of these registers and
 when there are more pointers than registers,
-their contents must be "spilled" into a set of tables.
-These tables are called "bounds tables" and the MPX
+their contents must be \(oqspilled\(cq into a set of tables.
+These tables are called \(oqbounds tables\(cq and the MPX
 .BR prctl ()
 operations control
 whether the kernel manages their allocation and freeing.
@@ -833,7 +833,8 @@ These calls fail if the CPU or kernel does not support MPX.
 Kernel support for MPX is enabled via the
 .BR CONFIG_X86_INTEL_MPX
 configuration option.
-You can check whether the CPU supports MPX by looking for the 'mpx'
+You can check whether the CPU supports MPX by looking for the
+.I mpx
 CPUID bit, like with the following command:
 .IP
 .in +4n
@@ -954,7 +955,7 @@ parent dies.
 .IP
 .IR Warning :
 .\" https://bugzilla.kernel.org/show_bug.cgi?id=43300
-the "parent" in this case is considered to be the
+the \(oqparent\(cq in this case is considered to be the
 .I thread
 that created this process.
 In other words, the signal will be sent when that thread terminates
@@ -1005,20 +1006,20 @@ in the location pointed to by
 .\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
 .\" commit bf06189e4d14641c0148bea16e9dd24943862215
 This is meaningful only when the Yama LSM is enabled and in mode 1
-("restricted ptrace", visible via
+(\(oqrestricted ptrace\(cq, visible via
 .IR /proc/sys/kernel/yama/ptrace_scope ).
-When a "ptracer process ID" is passed in \fIarg2\fP,
+When a \(oqptracer process ID\(cq is passed in \fIarg2\fP,
 the caller is declaring that the ptracer process can
 .BR ptrace (2)
 the calling process as if it were a direct process ancestor.
 Each
 .B PR_SET_PTRACER
-operation replaces the previous "ptracer process ID".
+operation replaces the previous \(oqptracer process ID\(cq.
 Employing
 .B PR_SET_PTRACER
 with
 .I arg2
-set to 0 clears the caller's "ptracer process ID".
+set to 0 clears the caller's \(oqptracer process ID\(cq.
 If
 .I arg2
 is
@@ -1139,7 +1140,7 @@ without the risk that the process is killed; see
 .\" prctl PR_SET_SECUREBITS
 .TP
 .BR PR_SET_SECUREBITS " (since Linux 2.6.26)"
-Set the "securebits" flags of the calling thread to the value supplied in
+Set the \(oqsecurebits\(cq flags of the calling thread to the value supplied in
 .IR arg2 .
 See
 .BR capabilities (7).
@@ -1147,7 +1148,7 @@ See
 .TP
 .BR PR_GET_SECUREBITS " (since Linux 2.6.26)"
 Return (as the function result)
-the "securebits" flags of the calling thread.
+the \(oqsecurebits\(cq flags of the calling thread.
 See
 .BR capabilities (7).
 .\" prctl PR_GET_SPECULATION_CTRL
@@ -1289,7 +1290,7 @@ in Linux 2.6.32.
 .TP
 .BR PR_SET_THP_DISABLE " (since Linux 3.15)"
 .\" commit a0715cc22601e8830ace98366c0c2bd8da52af52
-Set the state of the "THP disable" flag for the calling thread.
+Set the state of the \(oqTHP disable\(cq flag for the calling thread.
 If
 .I arg2
 has a nonzero value, the flag is set, otherwise it is cleared.
@@ -1298,14 +1299,14 @@ for disabling transparent huge pages
 for jobs where the code cannot be modified, and using a malloc hook with
 .BR madvise (2)
 is not an option (i.e., statically allocated data).
-The setting of the "THP disable" flag is inherited by a child created via
+The setting of the \(oqTHP disable\(cq flag is inherited by a child created via
 .BR fork (2)
 and is preserved across
 .BR execve (2).
 .\" prctl PR_GET_THP_DISABLE
 .TP
 .BR PR_GET_THP_DISABLE " (since Linux 3.15)"
-Return (as the function result) the current setting of the "THP disable"
+Return (as the function result) the current setting of the \(oqTHP disable\(cq
 flag for the calling thread:
 either 1, if the flag is set, or 0, if it is not.
 .\" prctl PR_GET_TID_ADDRESS
@@ -1336,21 +1337,21 @@ this operation expects a user-space buffer of 8 (not 4) bytes on these ABIs.
 .\" See https://lwn.net/Articles/369549/
 .\" commit 6976675d94042fbd446231d1bd8b7de71a980ada
 Each thread has two associated timer slack values:
-a "default" value, and a "current" value.
-This operation sets the "current" timer slack value for the calling thread.
+a \(oqdefault\(cq value, and a \(oqcurrent\(cq value.
+This operation sets the \(oqcurrent\(cq timer slack value for the calling thread.
 .I arg2
-is an unsigned long value, then maximum "current" value is ULONG_MAX and
-the minimum "current" value is 1.
+is an unsigned long value, then maximum \(oqcurrent\(cq value is ULONG_MAX and
+the minimum \(oqcurrent\(cq value is 1.
 If the nanosecond value supplied in
 .IR arg2
-is greater than zero, then the "current" value is set to this value.
+is greater than zero, then the \(oqcurrent\(cq value is set to this value.
 If
 .I arg2
 is equal to zero,
-the "current" timer slack is reset to the
-thread's "default" timer slack value.
+the \(oqcurrent\(cq timer slack is reset to the
+thread's \(oqdefault\(cq timer slack value.
 .IP
-The "current" timer slack is used by the kernel to group timer expirations
+The \(oqcurrent\(cq timer slack is used by the kernel to group timer expirations
 for the calling thread that are close to one another;
 as a consequence, timer expirations for the thread may be
 up to the specified number of nanoseconds late (but will never expire early).
@@ -1382,11 +1383,11 @@ a real-time scheduling policy (see
 .BR sched_setscheduler (2)).
 .IP
 When a new thread is created,
-the two timer slack values are made the same as the "current" value
+the two timer slack values are made the same as the \(oqcurrent\(cq value
 of the creating thread.
-Thereafter, a thread can adjust its "current" timer slack value via
+Thereafter, a thread can adjust its \(oqcurrent\(cq timer slack value via
 .BR PR_SET_TIMERSLACK .
-The "default" value can't be changed.
+The \(oqdefault\(cq value can't be changed.
 The timer slack values of
 .IR init
 (PID 1), the ancestor of all processes,
@@ -1396,7 +1397,7 @@ The timer slack value is inherited by a child created via
 and is preserved across
 .BR execve (2).
 .IP
-Since Linux 4.6, the "current" timer slack value of any process
+Since Linux 4.6, the \(oqcurrent\(cq timer slack value of any process
 can be examined and changed via the file
 .IR /proc/[pid]/timerslack_ns .
 See
@@ -1405,7 +1406,7 @@ See
 .TP
 .BR PR_GET_TIMERSLACK " (since Linux 2.6.28)"
 Return (as the function result)
-the "current" timer slack value of the calling thread.
+the \(oqcurrent\(cq timer slack value of the calling thread.
 .\" prctl PR_SET_TIMING
 .TP
 .BR PR_SET_TIMING " (since Linux 2.6.0)"
@@ -1817,7 +1818,7 @@ is
 and the caller does not have the
 .B CAP_SETPCAP
 capability,
-or tried to unset a "locked" flag,
+or tried to unset a \(oqlocked\(cq flag,
 or tried to set a flag whose corresponding locked flag was set
 (see
 .BR capabilities (7)).
-- 
2.1.4

Re: [PATCH 06/14] prctl.2: ffix quotation mark tweaks

[Michael Kerrisk (man-pages)]

Hello Dave,

On 5/12/20 6:36 PM, Dave Martin wrote:
> Convert quote marks used for information terms in prose to use
> \(oq .. \(cq, for better graphical rendering.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>

Again, this is a patch that I would prefer to see near the end 
of a series, rather than in the middle.

I'm currently agnostic about this change. But, I do not
want to apply this patch, since no other pages in man-pages
use \(oq...\(cq.

I haven't applied this patch. Luckily, that does not prevent
any of the later patches applying.

> ---
> 
> Note, this can lead to misrendering on badly-configured systems.
> However, many man pages do it.

Can you say some more about this please?

Cheers,

Michael

> In the C locale (or with -Tascii) the quotes still render as ' .
> ---
>  man2/prctl.2 | 71 ++++++++++++++++++++++++++++++------------------------------
>  1 file changed, 36 insertions(+), 35 deletions(-)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 1611448..7a3fc5c 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -188,7 +188,7 @@ library in the form of
>  If
>  .I arg2
>  is nonzero,
> -set the "child subreaper" attribute of the calling process;
> +set the \(oqchild subreaper\(cq attribute of the calling process;
>  if
>  .I arg2
>  is zero, unset the attribute.
> @@ -210,7 +210,7 @@ signal and will be able to
>  .BR wait (2)
>  on the process to discover its termination status.
>  .IP
> -The setting of the "child subreaper" attribute
> +The setting of the \(oqchild subreaper\(cq attribute
>  is not inherited by children created by
>  .BR fork (2)
>  and
> @@ -231,13 +231,13 @@ employ a subreaper process for similar reasons.
>  .\" prctl PR_GET_CHILD_SUBREAPER
>  .TP
>  .BR PR_GET_CHILD_SUBREAPER " (since Linux 3.4)"
> -Return the "child subreaper" setting of the caller,
> +Return the \(oqchild subreaper\(cq setting of the caller,
>  in the location pointed to by
>  .IR "(int\ *) arg2" .
>  .\" prctl PR_SET_DUMPABLE
>  .TP
>  .BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
> -Set the state of the "dumpable" attribute,
> +Set the state of the \(oqdumpable\(cq attribute,
>  which determines whether core dumps are produced for the calling process
>  upon delivery of a signal whose default behavior is to produce a core dump.
>  .IP
> @@ -263,7 +263,7 @@ for security reasons, this feature has been removed.
>  in
>  .BR proc (5).)
>  .IP
> -Normally, the "dumpable" attribue is set to 1.
> +Normally, the \(oqdumpable\(cq attribue is set to 1.
>  However, it is reset to the current value contained in the file
>  .IR /proc/sys/fs/\:suid_dumpable
>  (which by default has the value 0),
> @@ -539,19 +539,19 @@ must be zero.
>  .\" prctl PR_SET_KEEPCAPS
>  .TP
>  .BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
> -Set the state of the calling thread's "keep capabilities" flag.
> +Set the state of the calling thread's \(oqkeep capabilities\(cq flag.
>  The effect of this flag is described in
>  .BR capabilities (7).
>  .I arg2
>  must be either 0 (clear the flag)
>  or 1 (set the flag).
> -The "keep capabilities" value will be reset to 0 on subsequent calls to
> +The \(oqkeep capabilities\(cq value will be reset to 0 on subsequent calls to
>  .BR execve (2).
>  .\" prctl PR_GET_KEEPCAPS
>  .TP
>  .BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
>  Return (as the function result) the current state of the calling thread's
> -"keep capabilities" flag.
> +\(oqkeep capabilities\(cq flag.
>  See
>  .BR capabilities (7)
>  for a description of this flag.
> @@ -806,8 +806,8 @@ and a set of special instruction prefixes that tell the CPU on which
>  instructions it should do bounds enforcement.
>  There is a limited number of these registers and
>  when there are more pointers than registers,
> -their contents must be "spilled" into a set of tables.
> -These tables are called "bounds tables" and the MPX
> +their contents must be \(oqspilled\(cq into a set of tables.
> +These tables are called \(oqbounds tables\(cq and the MPX
>  .BR prctl ()
>  operations control
>  whether the kernel manages their allocation and freeing.
> @@ -833,7 +833,8 @@ These calls fail if the CPU or kernel does not support MPX.
>  Kernel support for MPX is enabled via the
>  .BR CONFIG_X86_INTEL_MPX
>  configuration option.
> -You can check whether the CPU supports MPX by looking for the 'mpx'
> +You can check whether the CPU supports MPX by looking for the
> +.I mpx
>  CPUID bit, like with the following command:
>  .IP
>  .in +4n
> @@ -954,7 +955,7 @@ parent dies.
>  .IP
>  .IR Warning :
>  .\" https://bugzilla.kernel.org/show_bug.cgi?id=43300
> -the "parent" in this case is considered to be the
> +the \(oqparent\(cq in this case is considered to be the
>  .I thread
>  that created this process.
>  In other words, the signal will be sent when that thread terminates
> @@ -1005,20 +1006,20 @@ in the location pointed to by
>  .\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
>  .\" commit bf06189e4d14641c0148bea16e9dd24943862215
>  This is meaningful only when the Yama LSM is enabled and in mode 1
> -("restricted ptrace", visible via
> +(\(oqrestricted ptrace\(cq, visible via
>  .IR /proc/sys/kernel/yama/ptrace_scope ).
> -When a "ptracer process ID" is passed in \fIarg2\fP,
> +When a \(oqptracer process ID\(cq is passed in \fIarg2\fP,
>  the caller is declaring that the ptracer process can
>  .BR ptrace (2)
>  the calling process as if it were a direct process ancestor.
>  Each
>  .B PR_SET_PTRACER
> -operation replaces the previous "ptracer process ID".
> +operation replaces the previous \(oqptracer process ID\(cq.
>  Employing
>  .B PR_SET_PTRACER
>  with
>  .I arg2
> -set to 0 clears the caller's "ptracer process ID".
> +set to 0 clears the caller's \(oqptracer process ID\(cq.
>  If
>  .I arg2
>  is
> @@ -1139,7 +1140,7 @@ without the risk that the process is killed; see
>  .\" prctl PR_SET_SECUREBITS
>  .TP
>  .BR PR_SET_SECUREBITS " (since Linux 2.6.26)"
> -Set the "securebits" flags of the calling thread to the value supplied in
> +Set the \(oqsecurebits\(cq flags of the calling thread to the value supplied in
>  .IR arg2 .
>  See
>  .BR capabilities (7).
> @@ -1147,7 +1148,7 @@ See
>  .TP
>  .BR PR_GET_SECUREBITS " (since Linux 2.6.26)"
>  Return (as the function result)
> -the "securebits" flags of the calling thread.
> +the \(oqsecurebits\(cq flags of the calling thread.
>  See
>  .BR capabilities (7).
>  .\" prctl PR_GET_SPECULATION_CTRL
> @@ -1289,7 +1290,7 @@ in Linux 2.6.32.
>  .TP
>  .BR PR_SET_THP_DISABLE " (since Linux 3.15)"
>  .\" commit a0715cc22601e8830ace98366c0c2bd8da52af52
> -Set the state of the "THP disable" flag for the calling thread.
> +Set the state of the \(oqTHP disable\(cq flag for the calling thread.
>  If
>  .I arg2
>  has a nonzero value, the flag is set, otherwise it is cleared.
> @@ -1298,14 +1299,14 @@ for disabling transparent huge pages
>  for jobs where the code cannot be modified, and using a malloc hook with
>  .BR madvise (2)
>  is not an option (i.e., statically allocated data).
> -The setting of the "THP disable" flag is inherited by a child created via
> +The setting of the \(oqTHP disable\(cq flag is inherited by a child created via
>  .BR fork (2)
>  and is preserved across
>  .BR execve (2).
>  .\" prctl PR_GET_THP_DISABLE
>  .TP
>  .BR PR_GET_THP_DISABLE " (since Linux 3.15)"
> -Return (as the function result) the current setting of the "THP disable"
> +Return (as the function result) the current setting of the \(oqTHP disable\(cq
>  flag for the calling thread:
>  either 1, if the flag is set, or 0, if it is not.
>  .\" prctl PR_GET_TID_ADDRESS
> @@ -1336,21 +1337,21 @@ this operation expects a user-space buffer of 8 (not 4) bytes on these ABIs.
>  .\" See https://lwn.net/Articles/369549/
>  .\" commit 6976675d94042fbd446231d1bd8b7de71a980ada
>  Each thread has two associated timer slack values:
> -a "default" value, and a "current" value.
> -This operation sets the "current" timer slack value for the calling thread.
> +a \(oqdefault\(cq value, and a \(oqcurrent\(cq value.
> +This operation sets the \(oqcurrent\(cq timer slack value for the calling thread.
>  .I arg2
> -is an unsigned long value, then maximum "current" value is ULONG_MAX and
> -the minimum "current" value is 1.
> +is an unsigned long value, then maximum \(oqcurrent\(cq value is ULONG_MAX and
> +the minimum \(oqcurrent\(cq value is 1.
>  If the nanosecond value supplied in
>  .IR arg2
> -is greater than zero, then the "current" value is set to this value.
> +is greater than zero, then the \(oqcurrent\(cq value is set to this value.
>  If
>  .I arg2
>  is equal to zero,
> -the "current" timer slack is reset to the
> -thread's "default" timer slack value.
> +the \(oqcurrent\(cq timer slack is reset to the
> +thread's \(oqdefault\(cq timer slack value.
>  .IP
> -The "current" timer slack is used by the kernel to group timer expirations
> +The \(oqcurrent\(cq timer slack is used by the kernel to group timer expirations
>  for the calling thread that are close to one another;
>  as a consequence, timer expirations for the thread may be
>  up to the specified number of nanoseconds late (but will never expire early).
> @@ -1382,11 +1383,11 @@ a real-time scheduling policy (see
>  .BR sched_setscheduler (2)).
>  .IP
>  When a new thread is created,
> -the two timer slack values are made the same as the "current" value
> +the two timer slack values are made the same as the \(oqcurrent\(cq value
>  of the creating thread.
> -Thereafter, a thread can adjust its "current" timer slack value via
> +Thereafter, a thread can adjust its \(oqcurrent\(cq timer slack value via
>  .BR PR_SET_TIMERSLACK .
> -The "default" value can't be changed.
> +The \(oqdefault\(cq value can't be changed.
>  The timer slack values of
>  .IR init
>  (PID 1), the ancestor of all processes,
> @@ -1396,7 +1397,7 @@ The timer slack value is inherited by a child created via
>  and is preserved across
>  .BR execve (2).
>  .IP
> -Since Linux 4.6, the "current" timer slack value of any process
> +Since Linux 4.6, the \(oqcurrent\(cq timer slack value of any process
>  can be examined and changed via the file
>  .IR /proc/[pid]/timerslack_ns .
>  See
> @@ -1405,7 +1406,7 @@ See
>  .TP
>  .BR PR_GET_TIMERSLACK " (since Linux 2.6.28)"
>  Return (as the function result)
> -the "current" timer slack value of the calling thread.
> +the \(oqcurrent\(cq timer slack value of the calling thread.
>  .\" prctl PR_SET_TIMING
>  .TP
>  .BR PR_SET_TIMING " (since Linux 2.6.0)"
> @@ -1817,7 +1818,7 @@ is
>  and the caller does not have the
>  .B CAP_SETPCAP
>  capability,
> -or tried to unset a "locked" flag,
> +or tried to unset a \(oqlocked\(cq flag,
>  or tried to set a flag whose corresponding locked flag was set
>  (see
>  .BR capabilities (7)).
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 06/14] prctl.2: ffix quotation mark tweaks

[Dave Martin]

On Wed, May 13, 2020 at 12:11:21PM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Dave,
> 
> On 5/12/20 6:36 PM, Dave Martin wrote:
> > Convert quote marks used for information terms in prose to use
> > \(oq .. \(cq, for better graphical rendering.
> > 
> > Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> 
> Again, this is a patch that I would prefer to see near the end 
> of a series, rather than in the middle.
> 
> I'm currently agnostic about this change. But, I do not
> want to apply this patch, since no other pages in man-pages
> use \(oq...\(cq.
> 
> I haven't applied this patch. Luckily, that does not prevent
> any of the later patches applying.

I'll be careful to move this sort of thing to the end of a series in
future.

This was a provocative patch, so I'm happy for it to be dropped.


The main motivation was that ' renders to PostScript etc. as a closing
quote, which is fine for apostrophes but not fine for an opening quote
mark.  Most of the current quotes in here are actually ", but I don't
see an actual promise from groff that that renders as a neutral glyph
either, so it seemed best to avoid.  For now " does seem to be rendered
with a neutral glyph (i.e., neither opening or closing).

> > ---
> > 
> > Note, this can lead to misrendering on badly-configured systems.
> > However, many man pages do it.
> 
> Can you say some more about this please?

Terminal character maps need to match LANG etc. in order for fancy
characters coming out of nroff to display correctly.

ssh attempts to send LANG across, but terminal sessions between systems
that have different locales installed can be a problem, as can dumb
serial links that don't magically pass the locale and terminal type
settings across.

The fact that I hit this problem a lot in some situations (particularly
the serial link case) suggested to me that fancy characters are
considered fine nowadays, but perhaps I'd need to dig into it some more
to understand the situation fully.

(There are one or two ' that should really be \(aq anyway, but I'll
try to address that separately.)

Cheers
---Dave

Re: [PATCH 06/14] prctl.2: ffix quotation mark tweaks

[Michael Kerrisk (man-pages)]

On 5/13/20 1:39 PM, Dave Martin wrote:
> On Wed, May 13, 2020 at 12:11:21PM +0200, Michael Kerrisk (man-pages) wrote:
>> Hello Dave,
>>
>> On 5/12/20 6:36 PM, Dave Martin wrote:
>>> Convert quote marks used for information terms in prose to use
>>> \(oq .. \(cq, for better graphical rendering.
>>>
>>> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
>>
>> Again, this is a patch that I would prefer to see near the end 
>> of a series, rather than in the middle.
>>
>> I'm currently agnostic about this change. But, I do not
>> want to apply this patch, since no other pages in man-pages
>> use \(oq...\(cq.
>>
>> I haven't applied this patch. Luckily, that does not prevent
>> any of the later patches applying.
> 
> I'll be careful to move this sort of thing to the end of a series in
> future.
> 
> This was a provocative patch, so I'm happy for it to be dropped.
> 
> 
> The main motivation was that ' renders to PostScript etc. as a closing
> quote, which is fine for apostrophes but not fine for an opening quote
> mark.  Most of the current quotes in here are actually ", but I don't
> see an actual promise from groff that that renders as a neutral glyph
> either, so it seemed best to avoid.  For now " does seem to be rendered
> with a neutral glyph (i.e., neither opening or closing).

See my commit 11b0b31a14bd2c7dcb0cf7bc815b4c1887444a89, just pushed,
which addresses the ' issues.

>>> ---
>>>
>>> Note, this can lead to misrendering on badly-configured systems.
>>> However, many man pages do it.
>>
>> Can you say some more about this please?
> 
> Terminal character maps need to match LANG etc. in order for fancy
> characters coming out of nroff to display correctly.
> 
> ssh attempts to send LANG across, but terminal sessions between systems
> that have different locales installed can be a problem, as can dumb
> serial links that don't magically pass the locale and terminal type
> settings across.
> 
> The fact that I hit this problem a lot in some situations (particularly
> the serial link case) suggested to me that fancy characters are
> considered fine nowadays, but perhaps I'd need to dig into it some more
> to understand the situation fully.

Thanks for the clarification.

> (There are one or two ' that should really be \(aq anyway, but I'll
> try to address that separately.)

See above. I presume that patch is what you wanted?

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 06/14] prctl.2: ffix quotation mark tweaks

[Dave Martin]

On Wed, May 13, 2020 at 01:46:22PM +0200, Michael Kerrisk (man-pages) wrote:
> On 5/13/20 1:39 PM, Dave Martin wrote:
> > On Wed, May 13, 2020 at 12:11:21PM +0200, Michael Kerrisk (man-pages) wrote:
> >> Hello Dave,
> >>
> >> On 5/12/20 6:36 PM, Dave Martin wrote:
> >>> Convert quote marks used for information terms in prose to use
> >>> \(oq .. \(cq, for better graphical rendering.
> >>>
> >>> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> >>
> >> Again, this is a patch that I would prefer to see near the end 
> >> of a series, rather than in the middle.
> >>
> >> I'm currently agnostic about this change. But, I do not
> >> want to apply this patch, since no other pages in man-pages
> >> use \(oq...\(cq.
> >>
> >> I haven't applied this patch. Luckily, that does not prevent
> >> any of the later patches applying.
> > 
> > I'll be careful to move this sort of thing to the end of a series in
> > future.
> > 
> > This was a provocative patch, so I'm happy for it to be dropped.
> > 
> > 
> > The main motivation was that ' renders to PostScript etc. as a closing
> > quote, which is fine for apostrophes but not fine for an opening quote
> > mark.  Most of the current quotes in here are actually ", but I don't
> > see an actual promise from groff that that renders as a neutral glyph
> > either, so it seemed best to avoid.  For now " does seem to be rendered
> > with a neutral glyph (i.e., neither opening or closing).
> 
> See my commit 11b0b31a14bd2c7dcb0cf7bc815b4c1887444a89, just pushed,
> which addresses the ' issues.
> 
> >>> ---
> >>>
> >>> Note, this can lead to misrendering on badly-configured systems.
> >>> However, many man pages do it.
> >>
> >> Can you say some more about this please?
> > 
> > Terminal character maps need to match LANG etc. in order for fancy
> > characters coming out of nroff to display correctly.
> > 
> > ssh attempts to send LANG across, but terminal sessions between systems
> > that have different locales installed can be a problem, as can dumb
> > serial links that don't magically pass the locale and terminal type
> > settings across.
> > 
> > The fact that I hit this problem a lot in some situations (particularly
> > the serial link case) suggested to me that fancy characters are
> > considered fine nowadays, but perhaps I'd need to dig into it some more
> > to understand the situation fully.
> 
> Thanks for the clarification.
> 
> > (There are one or two ' that should really be \(aq anyway, but I'll
> > try to address that separately.)
> 
> See above. I presume that patch is what you wanted?

Yup, works for me.

I'll keep an eye out for other instances, but those were the ones that
stood out.

Cheers
---Dave

[PATCH 07/14] prctl.2: Document removal of Intel MPX prctls

[Dave Martin]

The Intel MPX API was removed from Linux 5.4.  See Linux
commit f240652b6032 ("x86/mpx: Remove MPX APIs")

Document this change.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Dave Hansen <dave.hansen@linux.intel.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
---
 man2/prctl.2 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 7a3fc5c..a84fb1d 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -784,7 +784,7 @@ option enabled.
 .RE
 .\" prctl PR_MPX_ENABLE_MANAGEMENT
 .TP
-.BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19) "
+.BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19, removed in Linux 5.4; only on x86) "
 .\" commit fe3d197f84319d3bce379a9c0dc17b1f48ad358c
 .\" See also http://lwn.net/Articles/582712/
 .\" See also https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler
@@ -859,6 +859,12 @@ had been called.
 .IP
 For further information on Intel MPX, see the kernel source file
 .IR Documentation/x86/intel_mpx.txt .
+.IP
+.\" commit f240652b6032b48ad7fa35c5e701cc4c8d697c0b
+.\" See also https://lkml.kernel.org/r/20190705175321.DB42F0AD@viggo.jf.intel.com
+Due to a lack of toolchain support,
+.BR PR_MPX_ENABLE_MANAGEMENT " and " PR_MPX_DISABLE_MANAGEMENT
+are not supported by Linux 5.4 or later.
 .\" prctl PR_SET_NAME
 .TP
 .BR PR_SET_NAME " (since Linux 2.6.9)"
-- 
2.1.4

Re: [PATCH 07/14] prctl.2: Document removal of Intel MPX prctls

[Dave Hansen]

On 5/12/20 9:36 AM, Dave Martin wrote:
> The Intel MPX API was removed from Linux 5.4.  See Linux
> commit f240652b6032 ("x86/mpx: Remove MPX APIs")
> 
> Document this change.

Thanks for doing this!

Acked-by: Dave Hansen <dave.hansen@linux.intel.com>

Re: [PATCH 07/14] prctl.2: Document removal of Intel MPX prctls

[Michael Kerrisk (man-pages)]

On 5/12/20 6:36 PM, Dave Martin wrote:
> The Intel MPX API was removed from Linux 5.4.  See Linux
> commit f240652b6032 ("x86/mpx: Remove MPX APIs")
> 
> Document this change.

Thanks. Patch applied, with Dave H's Acked-by.

Cheers,

Michael

> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> Cc: Dave Hansen <dave.hansen@linux.intel.com>
> Cc: Thomas Gleixner <tglx@linutronix.de>
> ---
>  man2/prctl.2 | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 7a3fc5c..a84fb1d 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -784,7 +784,7 @@ option enabled.
>  .RE
>  .\" prctl PR_MPX_ENABLE_MANAGEMENT
>  .TP
> -.BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19) "
> +.BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19, removed in Linux 5.4; only on x86) "
>  .\" commit fe3d197f84319d3bce379a9c0dc17b1f48ad358c
>  .\" See also http://lwn.net/Articles/582712/
>  .\" See also https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler
> @@ -859,6 +859,12 @@ had been called.
>  .IP
>  For further information on Intel MPX, see the kernel source file
>  .IR Documentation/x86/intel_mpx.txt .
> +.IP
> +.\" commit f240652b6032b48ad7fa35c5e701cc4c8d697c0b
> +.\" See also https://lkml.kernel.org/r/20190705175321.DB42F0AD@viggo.jf.intel.com
> +Due to a lack of toolchain support,
> +.BR PR_MPX_ENABLE_MANAGEMENT " and " PR_MPX_DISABLE_MANAGEMENT
> +are not supported by Linux 5.4 or later.
>  .\" prctl PR_SET_NAME
>  .TP
>  .BR PR_SET_NAME " (since Linux 2.6.9)"
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 08/14] prctl.2: Work around bogus constant "maxsig" in PR_SET_PDEATHSIG

[Dave Martin]

The description of PR_SET_PDEATHSIG refers to "maxsig", which is
apparently intended to stand for the maximum defined signal number.

maxsig seems not to be a thing, even in the kernel.

Reword to use the standard constant NSIG.  (Discussion of SIGRTMIN
and SIGRTMAX seems out of scope here, and anyway is not relevant to
the kernel.)

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
---
 man2/prctl.2 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index a84fb1d..1e04859 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -955,7 +955,9 @@ will operate in the privilege-restricting mode described above.
 .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
 Set the parent-death signal
 of the calling process to \fIarg2\fP (either a signal value
-in the range 1..maxsig, or 0 to clear).
+in the range 1 ..
+.BR NSIG " \-"
+1, or 0 to clear).
 This is the signal that the calling process will get when its
 parent dies.
 .IP
-- 
2.1.4

Re: [PATCH 08/14] prctl.2: Work around bogus constant "maxsig" in PR_SET_PDEATHSIG

[Michael Kerrisk (man-pages)]

On 5/12/20 6:36 PM, Dave Martin wrote:
> The description of PR_SET_PDEATHSIG refers to "maxsig", which is
> apparently intended to stand for the maximum defined signal number.
> 
> maxsig seems not to be a thing, even in the kernel.
> 
> Reword to use the standard constant NSIG.  (Discussion of SIGRTMIN
> and SIGRTMAX seems out of scope here, and anyway is not relevant to
> the kernel.)

Thanks, Dave. Patch applied.

Cheers,

Michael

> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> ---
>  man2/prctl.2 | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index a84fb1d..1e04859 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -955,7 +955,9 @@ will operate in the privilege-restricting mode described above.
>  .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
>  Set the parent-death signal
>  of the calling process to \fIarg2\fP (either a signal value
> -in the range 1..maxsig, or 0 to clear).
> +in the range 1 ..
> +.BR NSIG " \-"
> +1, or 0 to clear).
>  This is the signal that the calling process will get when its
>  parent dies.
>  .IP
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 09/14] prctl.2: tfix minor punctuation in SPECULATION_CTRL prctls

[Dave Martin]

Fix a few very minor bits of punctuation in
PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
---
 man2/prctl.2 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 1e04859..e8eaf95 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1175,13 +1175,13 @@ The return value uses bits 0-3 with the following meaning:
 .TP
 .BR PR_SPEC_PRCTL
 Mitigation can be controlled per thread by
-.B PR_SET_SPECULATION_CTRL
+.BR PR_SET_SPECULATION_CTRL .
 .TP
 .BR PR_SPEC_ENABLE
 The speculation feature is enabled, mitigation is disabled.
 .TP
 .BR PR_SPEC_DISABLE
-The speculation feature is disabled, mitigation is enabled
+The speculation feature is disabled, mitigation is enabled.
 .TP
 .BR PR_SPEC_FORCE_DISABLE
 Same as
@@ -1228,11 +1228,11 @@ which is one of the following:
 The speculation feature is enabled, mitigation is disabled.
 .TP
 .BR PR_SPEC_DISABLE
-The speculation feature is disabled, mitigation is enabled
+The speculation feature is disabled, mitigation is enabled.
 .TP
 .BR PR_SPEC_FORCE_DISABLE
 Same as
-.B PR_SPEC_DISABLE
+.BR PR_SPEC_DISABLE ,
 but cannot be undone.
 A subsequent
 .B
-- 
2.1.4

Re: [PATCH 09/14] prctl.2: tfix minor punctuation in SPECULATION_CTRL prctls

[Michael Kerrisk (man-pages)]

On 5/12/20 6:36 PM, Dave Martin wrote:
> Fix a few very minor bits of punctuation in
> PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>

Thanks, Dave. Patch applied.

Cheers,

Michael

> ---
>  man2/prctl.2 | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 1e04859..e8eaf95 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1175,13 +1175,13 @@ The return value uses bits 0-3 with the following meaning:
>  .TP
>  .BR PR_SPEC_PRCTL
>  Mitigation can be controlled per thread by
> -.B PR_SET_SPECULATION_CTRL
> +.BR PR_SET_SPECULATION_CTRL .
>  .TP
>  .BR PR_SPEC_ENABLE
>  The speculation feature is enabled, mitigation is disabled.
>  .TP
>  .BR PR_SPEC_DISABLE
> -The speculation feature is disabled, mitigation is enabled
> +The speculation feature is disabled, mitigation is enabled.
>  .TP
>  .BR PR_SPEC_FORCE_DISABLE
>  Same as
> @@ -1228,11 +1228,11 @@ which is one of the following:
>  The speculation feature is enabled, mitigation is disabled.
>  .TP
>  .BR PR_SPEC_DISABLE
> -The speculation feature is disabled, mitigation is enabled
> +The speculation feature is disabled, mitigation is enabled.
>  .TP
>  .BR PR_SPEC_FORCE_DISABLE
>  Same as
> -.B PR_SPEC_DISABLE
> +.BR PR_SPEC_DISABLE ,
>  but cannot be undone.
>  A subsequent
>  .B
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 10/14] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls

[Dave Martin]

Add the PR_SPEC_INDIRECT_BRANCH "misfeature" added in Linux 4.20
for PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Tim Chen <tim.c.chen@linux.intel.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
---
 man2/prctl.2 | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index e8eaf95..66417cf 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1213,11 +1213,20 @@ arguments must be specified as 0; otherwise the call fails with the error
 .\" commit 356e4bfff2c5489e016fdb925adbf12a1e3950ee
 Sets the state of the speculation misfeature specified in
 .IR arg2 .
-Currently, the only permitted value for this argument is
+Currently, this argument must be one of:
+.RS
+.TP
 .B PR_SPEC_STORE_BYPASS
-(otherwise the call fails with the error
+speculative store bypass control, or
+.\" commit 9137bb27e60e554dab694eafa4cca241fa3a694f
+.TP
+.BR PR_SPEC_INDIRECT_BRANCH " (since Linux 4.20)"
+indirect branch speculation control.
+.RE
+.IP
+(Otherwise the call fails with the error
 .BR ENODEV ).
-This setting is a per-thread attribute.
+These settings are per-thread attributes.
 The
 .IR arg3
 argument is used to hand in the control value,
@@ -1235,13 +1244,16 @@ Same as
 .BR PR_SPEC_DISABLE ,
 but cannot be undone.
 A subsequent
-.B
-prctl(..., PR_SPEC_ENABLE)
+.BR prctl (\c
+.IR arg2 ,
+.BR PR_SPEC_ENABLE )
+with the same value for
+.I arg2
 will fail with the error
 .BR EPERM .
 .RE
 .IP
-Any other value in
+Any unsupported value in
 .IR arg3
 will result in the call failing with the error
 .BR ERANGE .
-- 
2.1.4

Re: [PATCH 10/14] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls

[Michael Kerrisk (man-pages)]

Hello Dave,

On 5/12/20 6:36 PM, Dave Martin wrote:
> Add the PR_SPEC_INDIRECT_BRANCH "misfeature" added in Linux 4.20
> for PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> Cc: Tim Chen <tim.c.chen@linux.intel.com>
> Cc: Thomas Gleixner <tglx@linutronix.de>

Thanks. Patch applied, but not yet pushed while I wait to see if any
Review/Ack arrives.

Also, could you please check the tweaks I note below.

> ---
>  man2/prctl.2 | 24 ++++++++++++++++++------
>  1 file changed, 18 insertions(+), 6 deletions(-)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index e8eaf95..66417cf 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1213,11 +1213,20 @@ arguments must be specified as 0; otherwise the call fails with the error
>  .\" commit 356e4bfff2c5489e016fdb925adbf12a1e3950ee
>  Sets the state of the speculation misfeature specified in
>  .IR arg2 .
> -Currently, the only permitted value for this argument is
> +Currently, this argument must be one of:
> +.RS
> +.TP
>  .B PR_SPEC_STORE_BYPASS
> -(otherwise the call fails with the error
> +speculative store bypass control, or

s/speculative/enable speculative/

> +.\" commit 9137bb27e60e554dab694eafa4cca241fa3a694f
> +.TP
> +.BR PR_SPEC_INDIRECT_BRANCH " (since Linux 4.20)"
> +indirect branch speculation control.

s/indirect/enable indirect/

> +.RE
> +.IP
> +(Otherwise the call fails with the error
>  .BR ENODEV ).
> -This setting is a per-thread attribute.
> +These settings are per-thread attributes.
>  The
>  .IR arg3
>  argument is used to hand in the control value,
> @@ -1235,13 +1244,16 @@ Same as
>  .BR PR_SPEC_DISABLE ,
>  but cannot be undone.
>  A subsequent
> -.B
> -prctl(..., PR_SPEC_ENABLE)
> +.BR prctl (\c
> +.IR arg2 ,
> +.BR PR_SPEC_ENABLE )
> +with the same value for
> +.I arg2
>  will fail with the error
>  .BR EPERM .
>  .RE
>  .IP
> -Any other value in
> +Any unsupported value in
>  .IR arg3
>  will result in the call failing with the error
>  .BR ERANGE .

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 10/14] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls

[Dave Martin]

On Wed, May 13, 2020 at 01:21:12PM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Dave,
> 
> On 5/12/20 6:36 PM, Dave Martin wrote:
> > Add the PR_SPEC_INDIRECT_BRANCH "misfeature" added in Linux 4.20
> > for PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.
> > 
> > Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> > Cc: Tim Chen <tim.c.chen@linux.intel.com>
> > Cc: Thomas Gleixner <tglx@linutronix.de>
> 
> Thanks. Patch applied, but not yet pushed while I wait to see if any
> Review/Ack arrives.
> 
> Also, could you please check the tweaks I note below.
> 
> > ---
> >  man2/prctl.2 | 24 ++++++++++++++++++------
> >  1 file changed, 18 insertions(+), 6 deletions(-)
> > 
> > diff --git a/man2/prctl.2 b/man2/prctl.2
> > index e8eaf95..66417cf 100644
> > --- a/man2/prctl.2
> > +++ b/man2/prctl.2
> > @@ -1213,11 +1213,20 @@ arguments must be specified as 0; otherwise the call fails with the error
> >  .\" commit 356e4bfff2c5489e016fdb925adbf12a1e3950ee
> >  Sets the state of the speculation misfeature specified in
> >  .IR arg2 .
> > -Currently, the only permitted value for this argument is
> > +Currently, this argument must be one of:
> > +.RS
> > +.TP
> >  .B PR_SPEC_STORE_BYPASS
> > -(otherwise the call fails with the error
> > +speculative store bypass control, or
> 
> s/speculative/enable speculative/
> 
> > +.\" commit 9137bb27e60e554dab694eafa4cca241fa3a694f
> > +.TP
> > +.BR PR_SPEC_INDIRECT_BRANCH " (since Linux 4.20)"
> > +indirect branch speculation control.
> 
> s/indirect/enable indirect/

That doesn't seem quite right.

arg2 just identifies what behaviour to configure.
It's arg3 that says whether to disable / enable it or whatever.


While editing this I did wonder whether the "control" was helpful.
Maybe just dropping that word from these entries would help.

[...]

Cheers
---Dave

Re: [PATCH 10/14] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls

[Michael Kerrisk (man-pages)]

On 5/13/20 1:49 PM, Dave Martin wrote:
> On Wed, May 13, 2020 at 01:21:12PM +0200, Michael Kerrisk (man-pages) wrote:
>> Hello Dave,
>>
>> On 5/12/20 6:36 PM, Dave Martin wrote:
>>> Add the PR_SPEC_INDIRECT_BRANCH "misfeature" added in Linux 4.20
>>> for PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.
>>>
>>> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
>>> Cc: Tim Chen <tim.c.chen@linux.intel.com>
>>> Cc: Thomas Gleixner <tglx@linutronix.de>
>>
>> Thanks. Patch applied, but not yet pushed while I wait to see if any
>> Review/Ack arrives.
>>
>> Also, could you please check the tweaks I note below.
>>
>>> ---
>>>  man2/prctl.2 | 24 ++++++++++++++++++------
>>>  1 file changed, 18 insertions(+), 6 deletions(-)
>>>
>>> diff --git a/man2/prctl.2 b/man2/prctl.2
>>> index e8eaf95..66417cf 100644
>>> --- a/man2/prctl.2
>>> +++ b/man2/prctl.2
>>> @@ -1213,11 +1213,20 @@ arguments must be specified as 0; otherwise the call fails with the error
>>>  .\" commit 356e4bfff2c5489e016fdb925adbf12a1e3950ee
>>>  Sets the state of the speculation misfeature specified in
>>>  .IR arg2 .
>>> -Currently, the only permitted value for this argument is
>>> +Currently, this argument must be one of:
>>> +.RS
>>> +.TP
>>>  .B PR_SPEC_STORE_BYPASS
>>> -(otherwise the call fails with the error
>>> +speculative store bypass control, or
>>
>> s/speculative/enable speculative/
>>
>>> +.\" commit 9137bb27e60e554dab694eafa4cca241fa3a694f
>>> +.TP
>>> +.BR PR_SPEC_INDIRECT_BRANCH " (since Linux 4.20)"
>>> +indirect branch speculation control.
>>
>> s/indirect/enable indirect/
> 
> That doesn't seem quite right.

My goof, not looking at the bigger context of the patch.

> 
> arg2 just identifies what behaviour to configure.
> It's arg3 that says whether to disable / enable it or whatever.
> 
> 
> While editing this I did wonder whether the "control" was helpful.
> Maybe just dropping that word from these entries would help.

Okay I tried to fix things, and made also some other edits.
How does the following look to you?

      PR_SET_SPECULATION_CTRL (since Linux 4.17)
              Sets the state of the speculation misfeature  specified  in
              arg2.   The  speculation-misfeature settings are per-thread
              attributes.

              Currently, arg2 must be one of:

              PR_SPEC_STORE_BYPASS
                     Set the state of the speculative store  bypass  mis‐
                     feature.

              PR_SPEC_INDIRECT_BRANCH (since Linux 4.20)
                     Set  the  state  of  the indirect branch speculation
                     misfeature.

              If arg2 does not have one of the  above  values,  then  the
              call fails with the error ENODEV.

              The  arg3  argument  is  used to hand in the control value,
              which is one of the following:

              ...

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 10/14] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls

[Dave Martin]

On Wed, May 13, 2020 at 02:06:38PM +0200, Michael Kerrisk (man-pages) wrote:
> On 5/13/20 1:49 PM, Dave Martin wrote:
> > On Wed, May 13, 2020 at 01:21:12PM +0200, Michael Kerrisk (man-pages) wrote:
> >> Hello Dave,
> >>
> >> On 5/12/20 6:36 PM, Dave Martin wrote:
> >>> Add the PR_SPEC_INDIRECT_BRANCH "misfeature" added in Linux 4.20
> >>> for PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.
> >>>
> >>> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> >>> Cc: Tim Chen <tim.c.chen@linux.intel.com>
> >>> Cc: Thomas Gleixner <tglx@linutronix.de>
> >>
> >> Thanks. Patch applied, but not yet pushed while I wait to see if any
> >> Review/Ack arrives.
> >>
> >> Also, could you please check the tweaks I note below.
> >>
> >>> ---
> >>>  man2/prctl.2 | 24 ++++++++++++++++++------
> >>>  1 file changed, 18 insertions(+), 6 deletions(-)
> >>>
> >>> diff --git a/man2/prctl.2 b/man2/prctl.2
> >>> index e8eaf95..66417cf 100644
> >>> --- a/man2/prctl.2
> >>> +++ b/man2/prctl.2
> >>> @@ -1213,11 +1213,20 @@ arguments must be specified as 0; otherwise the call fails with the error
> >>>  .\" commit 356e4bfff2c5489e016fdb925adbf12a1e3950ee
> >>>  Sets the state of the speculation misfeature specified in
> >>>  .IR arg2 .
> >>> -Currently, the only permitted value for this argument is
> >>> +Currently, this argument must be one of:
> >>> +.RS
> >>> +.TP
> >>>  .B PR_SPEC_STORE_BYPASS
> >>> -(otherwise the call fails with the error
> >>> +speculative store bypass control, or
> >>
> >> s/speculative/enable speculative/
> >>
> >>> +.\" commit 9137bb27e60e554dab694eafa4cca241fa3a694f
> >>> +.TP
> >>> +.BR PR_SPEC_INDIRECT_BRANCH " (since Linux 4.20)"
> >>> +indirect branch speculation control.
> >>
> >> s/indirect/enable indirect/
> > 
> > That doesn't seem quite right.
> 
> My goof, not looking at the bigger context of the patch.
> 
> > 
> > arg2 just identifies what behaviour to configure.
> > It's arg3 that says whether to disable / enable it or whatever.
> > 
> > 
> > While editing this I did wonder whether the "control" was helpful.
> > Maybe just dropping that word from these entries would help.
> 
> Okay I tried to fix things, and made also some other edits.
> How does the following look to you?
> 
>       PR_SET_SPECULATION_CTRL (since Linux 4.17)
>               Sets the state of the speculation misfeature  specified  in
>               arg2.   The  speculation-misfeature settings are per-thread
>               attributes.
> 
>               Currently, arg2 must be one of:
> 
>               PR_SPEC_STORE_BYPASS
>                      Set the state of the speculative store  bypass  mis‐
>                      feature.
> 
>               PR_SPEC_INDIRECT_BRANCH (since Linux 4.20)
>                      Set  the  state  of  the indirect branch speculation
>                      misfeature.
> 
>               If arg2 does not have one of the  above  values,  then  the
>               call fails with the error ENODEV.
> 
>               The  arg3  argument  is  used to hand in the control value,
>               which is one of the following:
> 
>               ...

Look OK to me.

I thought it sounded odd to "set the state" of a silicon bug, but that
was a bogus concern.

This isn't about bugs, but intentional, often configurable behaviours in
the silicon that happen to have harmful side effects.

It could be more terse to say "configure" instead of "set the state of",
but either way works for me.

Cheers
---Dave

[PATCH 11/14] prctl.2: Add PR_SPEC_DISABLE_NOEXEC for SPECULATION_CTRL prctls

[Dave Martin]

Add the PR_SPEC_DISABLE_NOEXEC mode added in Linux 5.1
for the PR_SPEC_STORE_BYPASS "misfeature" of
PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Waiman Long <longman@redhat.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
---
 man2/prctl.2 | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 66417cf..2361b44 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1187,6 +1187,12 @@ The speculation feature is disabled, mitigation is enabled.
 Same as
 .B PR_SPEC_DISABLE
 but cannot be undone.
+.TP
+.BR PR_SPEC_DISABLE_NOEXEC " (since Linux 5.1)"
+Same as
+.BR PR_SPEC_DISABLE ,
+but but the state will be cleared on
+.BR execve (2).
 .RE
 .IP
 If all bits are 0,
@@ -1251,6 +1257,17 @@ with the same value for
 .I arg2
 will fail with the error
 .BR EPERM .
+.\" commit 71368af9027f18fe5d1c6f372cfdff7e4bde8b48
+.TP
+.BR PR_SPEC_DISABLE_NOEXEC " (since Linux 5.1)"
+Same as
+.BR PR_SPEC_DISABLE ,
+but but the state will be cleared on
+.BR execve (2).
+Currently only supported for
+.I arg2
+equal to
+.B PR_SPEC_STORE_BYPASS.
 .RE
 .IP
 Any unsupported value in
@@ -1898,11 +1915,12 @@ was
 .BR PR_SET_SPECULATION_CTRL
 and
 .IR arg3
-is neither
+is not
 .BR PR_SPEC_ENABLE ,
 .BR PR_SPEC_DISABLE ,
+.BR PR_SPEC_FORCE_DISABLE ,
 nor
-.BR PR_SPEC_FORCE_DISABLE .
+.BR PR_SPEC_DISABLE_NOEXEC .
 .SH VERSIONS
 The
 .BR prctl ()
-- 
2.1.4

[PATCH 12/14] prctl.2: Clarify the unsupported hardware case of EINVAL

[Dave Martin]

prctls that are architecture-specific won't work on other
architectures, and arch-specific prctls that manipulate optional
hardware features likewise won't work if that hardware feature is
not present.

The established pattern seems to be to treat such prctls as if they
are unimplemented, when attempted on the wrong hardware.

Cover these cases with some generic weasel words in the closet
existing EINVAL clause.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
---
 man2/prctl.2 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 2361b44..7f511d2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1616,7 +1616,8 @@ is an invalid address.
 .B EINVAL
 The value of
 .I option
-is not recognized.
+is not recognized,
+or not supported on this system.
 .TP
 .B EINVAL
 .I option
-- 
2.1.4

Re: [PATCH 12/14] prctl.2: Clarify the unsupported hardware case of EINVAL

[Michael Kerrisk (man-pages)]

Hello Dave,

On 5/12/20 6:36 PM, Dave Martin wrote:
> prctls that are architecture-specific won't work on other
> architectures, and arch-specific prctls that manipulate optional
> hardware features likewise won't work if that hardware feature is
> not present.
> 
> The established pattern seems to be to treat such prctls as if they
> are unimplemented, when attempted on the wrong hardware.
> 
> Cover these cases with some generic weasel words in the closet
> existing EINVAL clause.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>

Thanks. Patch applied

Cheers,

Michael

> ---
>  man2/prctl.2 | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 2361b44..7f511d2 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1616,7 +1616,8 @@ is an invalid address.
>  .B EINVAL
>  The value of
>  .I option
> -is not recognized.
> +is not recognized,
> +or not supported on this system.
>  .TP
>  .B EINVAL
>  .I option
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 13/14] prctl.2: Add SVE prctls (arm64)

[Dave Martin]

Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL
prctls added in Linux 4.15 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Catalin Marinas <catalin.marinas@arm.com>
Cc: Will Deacon <will@kernel.org>

---

I wrote the SVE support originally, so I probably have this one
halfway right.

The explantion added is not exhaustive, but I didn't want it to be too
verbose.  I may trim it a bit and move the detail to a dedicated page
later on, but this is better than nothing in the meantime.
---
 man2/prctl.2 | 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 7f511d2..dd16227 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1291,6 +1291,104 @@ call failing with the error
 .BR ENXIO .
 For further details, see the kernel source file
 .IR Documentation/admin-guide/kernel-parameters.txt .
+.\" prctl PR_SVE_SET_VL
+.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
+.\" linux-5.6/Documentation/arm64/sve.rst
+.TP
+.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
+Configure the thread's SVE vector length,
+as specified by
+.IR arg2 .
+Arguments
+.IR arg3 ", " arg4 " and " arg5
+are ignored.
+.IP
+The bits of
+.I arg2
+corresponding to
+.B SVE_VL_LEN_MASK
+must be set to the desired vector length in bytes.
+In addition,
+.I arg2
+may include zero or more of the following flags:
+.RS
+.TP
+.B PR_SVE_VL_INHERIT
+Inherit the configured vector length across
+.BR execve (2).
+.TP
+.B PR_SVE_SET_VL_ONEXEC
+Defer the change until the next
+.BR execve (2)
+in this thread.
+If
+.B PR_SVE_VL_INHERIT
+is also included in
+.IR arg2 ,
+it takes effect
+.I after
+this deferred change.
+.RE
+.IP
+On success, the vector length and flags are set as requested,
+and any deferred change that was pending immediately before the
+.B PR_SVE_SET_VL
+call is canceled.
+If
+.B PR_SVE_SET_VL_ONEXEC
+was included in
+.IR arg2 ,
+the returned value describes the configuration
+scheduled to take effect at the next
+.BR execve (2).
+Otherwise, the effect is immediate and
+the returned value describes the new configuration.
+The returned value is encoded in the same way as the return value of
+.BR PR_SVE_GET_VL .
+.IP
+If neither of the above flags is included in
+.IR arg2 ,
+a subsequent
+.BR execve (2)
+resets the vector length to the default value configured in
+.IR /proc/sys/abi/sve_default_vector_length .
+.IP
+The actual vector length configured by this operation
+is the greatest vector length supported by the platform
+that does not exceed
+.I arg2
+&
+.BR PR_SVE_VL_LEN_MASK .
+.IP
+The configuration (including any pending deferred change)
+is inherited across
+.BR fork (2)
+and
+.BR clone (2).
+.\" prctl PR_SVE_GET_VL
+.TP
+.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
+Get the thread's current SVE vector length configuration,
+as configured by
+.BR PR_SVE_SET_VL .
+.IP
+If successful, the return value describes the
+.I current
+configuration.
+The bits corresponding to
+.B PR_SVE_VL_LEN_MASK
+contain the currently configured vector length in bytes.
+The bit corresponding to
+.B PR_SVE_VL_INHERIT
+indicates whether the vector length will be inherited
+across
+.BR execve (2).
+.IP
+Note that there is no way determine whether there is
+a pending vector length change that has not yet taken effect.
+.IP
+Providing that the kernel and platform support SVE,
+this operation always succeeds.
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1534,6 +1632,8 @@ On success,
 .BR PR_GET_NO_NEW_PRIVS ,
 .BR PR_GET_SECUREBITS ,
 .BR PR_GET_SPECULATION_CTRL ,
+.BR PR_SVE_GET_VL ,
+.BR PR_SVE_SET_VL ,
 .BR PR_GET_THP_DISABLE ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
@@ -1817,6 +1917,18 @@ and unused arguments to
 .BR prctl ()
 are not 0.
 .TP
+.B EINVAL
+.I option
+was
+.B PR_SVE_SET_VL
+and
+.I arg2
+contains invalid flags, or
+.I arg2
+&
+.B SVE_VL_LEN_MASK
+is not a valid vector length.
+.TP
 .B ENODEV
 .I option
 was
-- 
2.1.4

Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)

[Will Deacon]

Hi Dave,

On Tue, May 12, 2020 at 05:36:58PM +0100, Dave Martin wrote:
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 7f511d2..dd16227 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1291,6 +1291,104 @@ call failing with the error
>  .BR ENXIO .
>  For further details, see the kernel source file
>  .IR Documentation/admin-guide/kernel-parameters.txt .
> +.\" prctl PR_SVE_SET_VL
> +.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
> +.\" linux-5.6/Documentation/arm64/sve.rst
> +.TP
> +.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
> +Configure the thread's SVE vector length,
> +as specified by
> +.IR arg2 .
> +Arguments
> +.IR arg3 ", " arg4 " and " arg5
> +are ignored.

Bugger, did we forget to force these to zero? I guess we should write the
man-page first next time :(

> +.IP
> +The bits of
> +.I arg2
> +corresponding to
> +.B SVE_VL_LEN_MASK

PR_SVE_LEN_MASK

> +must be set to the desired vector length in bytes.
> +In addition,
> +.I arg2
> +may include zero or more of the following flags:
> +.RS
> +.TP
> +.B PR_SVE_VL_INHERIT
> +Inherit the configured vector length across
> +.BR execve (2).
> +.TP
> +.B PR_SVE_SET_VL_ONEXEC
> +Defer the change until the next
> +.BR execve (2)
> +in this thread.

(aside, it's weird that we didn't allocate (1<<16) for one of these flags)

> +If
> +.B PR_SVE_VL_INHERIT
> +is also included in
> +.IR arg2 ,
> +it takes effect
> +.I after
> +this deferred change.

I find this a bit hard to follow, since it's not clear to me whether the
INHERIT flag is effectively set before or after the next execve(). In other
words, if both PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT are specified,
is the vector length preserved or reset on the next execve()?

> +.RE
> +.IP
> +On success, the vector length and flags are set as requested,
> +and any deferred change that was pending immediately before the
> +.B PR_SVE_SET_VL
> +call is canceled.

Huh, turns out 'canceled' is a valid US spelling. Fair enough, but it looks
wrong to me ;)

> +If
> +.B PR_SVE_SET_VL_ONEXEC
> +was included in
> +.IR arg2 ,
> +the returned value describes the configuration
> +scheduled to take effect at the next
> +.BR execve (2).

"describes the configuration" how?

> +Otherwise, the effect is immediate and
> +the returned value describes the new configuration.
> +The returned value is encoded in the same way as the return value of
> +.BR PR_SVE_GET_VL .

Aha. Maybe move this bit up slightly?

> +.IP
> +If neither of the above flags is included in

are included

> +.IR arg2 ,
> +a subsequent
> +.BR execve (2)
> +resets the vector length to the default value configured in
> +.IR /proc/sys/abi/sve_default_vector_length .
> +.IP
> +The actual vector length configured by this operation
> +is the greatest vector length supported by the platform
> +that does not exceed
> +.I arg2
> +&
> +.BR PR_SVE_VL_LEN_MASK .
> +.IP
> +The configuration (including any pending deferred change)
> +is inherited across
> +.BR fork (2)
> +and
> +.BR clone (2).
> +.\" prctl PR_SVE_GET_VL
> +.TP
> +.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
> +Get the thread's current SVE vector length configuration,
> +as configured by
> +.BR PR_SVE_SET_VL .

It doesn't *have* to be configured by PR_SVE_SET_VL though, right?

> +.IP
> +If successful, the return value describes the
> +.I current
> +configuration.

(aside: prctl() returns int, so we can't ever allocate past bit 30 in arg2.
Might be worth a note somewhere in the kernel).

> +The bits corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +contain the currently configured vector length in bytes.
> +The bit corresponding to
> +.B PR_SVE_VL_INHERIT
> +indicates whether the vector length will be inherited
> +across
> +.BR execve (2).
> +.IP
> +Note that there is no way determine whether there is

to determine

> +a pending vector length change that has not yet taken effect.
> +.IP
> +Providing that the kernel and platform support SVE,
> +this operation always succeeds.
>  .\"
>  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
> @@ -1534,6 +1632,8 @@ On success,
>  .BR PR_GET_NO_NEW_PRIVS ,
>  .BR PR_GET_SECUREBITS ,
>  .BR PR_GET_SPECULATION_CTRL ,
> +.BR PR_SVE_GET_VL ,
> +.BR PR_SVE_SET_VL ,
>  .BR PR_GET_THP_DISABLE ,
>  .BR PR_GET_TIMING ,
>  .BR PR_GET_TIMERSLACK ,
> @@ -1817,6 +1917,18 @@ and unused arguments to
>  .BR prctl ()
>  are not 0.
>  .TP
> +.B EINVAL
> +.I option
> +was
> +.B PR_SVE_SET_VL
> +and
> +.I arg2
> +contains invalid flags, or
> +.I arg2
> +&
> +.B SVE_VL_LEN_MASK
> +is not a valid vector length.
> +.TP

PR_SVE_GET_VL can return -EINVAL if SVE is not supported.

Will

Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)

[Dave Martin]

On Wed, May 13, 2020 at 09:43:52AM +0100, Will Deacon wrote:
> Hi Dave,
> 
> On Tue, May 12, 2020 at 05:36:58PM +0100, Dave Martin wrote:
> > diff --git a/man2/prctl.2 b/man2/prctl.2
> > index 7f511d2..dd16227 100644
> > --- a/man2/prctl.2
> > +++ b/man2/prctl.2
> > @@ -1291,6 +1291,104 @@ call failing with the error
> >  .BR ENXIO .
> >  For further details, see the kernel source file
> >  .IR Documentation/admin-guide/kernel-parameters.txt .
> > +.\" prctl PR_SVE_SET_VL
> > +.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
> > +.\" linux-5.6/Documentation/arm64/sve.rst
> > +.TP
> > +.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
> > +Configure the thread's SVE vector length,
> > +as specified by
> > +.IR arg2 .
> > +Arguments
> > +.IR arg3 ", " arg4 " and " arg5
> > +are ignored.
> 
> Bugger, did we forget to force these to zero? I guess we should write the
> man-page first next time :(

Not an accident, but there does seem to be some inconsistency in policy
among the various prctls here.

glibc explicitly has

	extern int prctl (int __option, ...);

(and nobody has to write _exit(0, 0, 0, 0, 0, 0) after all.)

Is there some agreed rationale for requiring redundant arguments to be
supplied explicitly as zero?  For now there are likely to be few users
of this, so we _might_ get away with changing the behaviour here if it's
considered important enough.

There is no forwards compatibility problem with this prctl though,
because there are spare bits in arg2 which can "turn on" additional
args if needed.

Also, it's implausible that PR_SVE_GET_VL will ever want an argument.

There are still 2 billion unallocated prctl numbers, so new prctls can
always be added if there's ever a need to work around these limitations,
but it seems extremely unlikely.

> 
> > +.IP
> > +The bits of
> > +.I arg2
> > +corresponding to
> > +.B SVE_VL_LEN_MASK
> 
> PR_SVE_LEN_MASK

Hmm, not sure how that happened.  Good spot!

I'll recheck that all the names are real when reposting.

> > +must be set to the desired vector length in bytes.
> > +In addition,
> > +.I arg2
> > +may include zero or more of the following flags:
> > +.RS
> > +.TP
> > +.B PR_SVE_VL_INHERIT
> > +Inherit the configured vector length across
> > +.BR execve (2).
> > +.TP
> > +.B PR_SVE_SET_VL_ONEXEC
> > +Defer the change until the next
> > +.BR execve (2)
> > +in this thread.
> 
> (aside, it's weird that we didn't allocate (1<<16) for one of these flags)

The flag definitions are shared with ptrace: ptrace is the
SVE_PT_REGS_SVE format selection bit, which isn't relevant to the prctl.

Maybe it would have made more sense to keep the definitions completely
separate, but it's there now.

> > +If
> > +.B PR_SVE_VL_INHERIT
> > +is also included in
> > +.IR arg2 ,
> > +it takes effect
> > +.I after
> > +this deferred change.
> 
> I find this a bit hard to follow, since it's not clear to me whether the
> INHERIT flag is effectively set before or after the next execve(). In other
> words, if both PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT are specified,
> is the vector length preserved or reset on the next execve()?

It makes no difference, because the ONEXEC handling takes priority over
the INHERIT handling. But either way INHERIT is never cleared by execve()
and will apply at subsequent execs().

Explaining all this properly seems out of scope here.  Maybe this should
be trimmed down rather than elaborated?  Or perhaps just explain it in
terms of what the kernel does instead of futile attempts to make it
intuitive?

Ultimately I'll probably write a separate page or pages for SVE and other
arm64 specifics.

> > +.RE
> > +.IP
> > +On success, the vector length and flags are set as requested,
> > +and any deferred change that was pending immediately before the
> > +.B PR_SVE_SET_VL
> > +call is canceled.
> 
> Huh, turns out 'canceled' is a valid US spelling. Fair enough, but it looks
> wrong to me ;)

Yeah, I know, but the man pages do have a documented policy on this...

prctl.2 has a lot of authors, so having mixed spellings could get
particularly messy.

> 
> > +If
> > +.B PR_SVE_SET_VL_ONEXEC
> > +was included in
> > +.IR arg2 ,
> > +the returned value describes the configuration
> > +scheduled to take effect at the next
> > +.BR execve (2).
> 
> "describes the configuration" how?
> 
> > +Otherwise, the effect is immediate and
> > +the returned value describes the new configuration.
> > +The returned value is encoded in the same way as the return value of
> > +.BR PR_SVE_GET_VL .
> 
> Aha. Maybe move this bit up slightly?

Yes, I'll reorder that.

> 
> > +.IP
> > +If neither of the above flags is included in
> 
> are included

Debatable.

The subject of the verb here is not "flags" (plural), but "neither of
the above flags" (which is more nuanced, though it can be interpreted
as singular).  Usage varies, and I don't consider this wrong.

> > +.IR arg2 ,
> > +a subsequent
> > +.BR execve (2)
> > +resets the vector length to the default value configured in
> > +.IR /proc/sys/abi/sve_default_vector_length .
> > +.IP
> > +The actual vector length configured by this operation
> > +is the greatest vector length supported by the platform
> > +that does not exceed
> > +.I arg2
> > +&
> > +.BR PR_SVE_VL_LEN_MASK .
> > +.IP
> > +The configuration (including any pending deferred change)
> > +is inherited across
> > +.BR fork (2)
> > +and
> > +.BR clone (2).
> > +.\" prctl PR_SVE_GET_VL
> > +.TP
> > +.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
> > +Get the thread's current SVE vector length configuration,
> > +as configured by
> > +.BR PR_SVE_SET_VL .
> 
> It doesn't *have* to be configured by PR_SVE_SET_VL though, right?

No, "as" here is trying to mean that PR_SVE_SET_VL illustrates how the
vl can be set, not that it is the only way.

Maybe just delete that clause?  I'm not sure it adds much.

> > +.IP
> > +If successful, the return value describes the
> > +.I current
> > +configuration.
> 
> (aside: prctl() returns int, so we can't ever allocate past bit 30 in arg2.
> Might be worth a note somewhere in the kernel).

Agreed.  The chance of adding more bits seemed negligible, but dropping
a comment in would probably be a good idea.

Maybe we could redocument PR_SVE_SET_VL's arg2 as an int.  Passing an
int must survive the variadic argument marshaling of the glibc prctl()
wrapper, otherwise passing the existing #defines without an explicit
case to long would already break.

I'll probably just add the comment for now though.

> > +The bits corresponding to
> > +.B PR_SVE_VL_LEN_MASK
> > +contain the currently configured vector length in bytes.
> > +The bit corresponding to
> > +.B PR_SVE_VL_INHERIT
> > +indicates whether the vector length will be inherited
> > +across
> > +.BR execve (2).
> > +.IP
> > +Note that there is no way determine whether there is
> 
> to determine

Ack

> > +a pending vector length change that has not yet taken effect.
> > +.IP
> > +Providing that the kernel and platform support SVE,
> > +this operation always succeeds.
> >  .\"
> >  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
> >  .TP
> > @@ -1534,6 +1632,8 @@ On success,
> >  .BR PR_GET_NO_NEW_PRIVS ,
> >  .BR PR_GET_SECUREBITS ,
> >  .BR PR_GET_SPECULATION_CTRL ,
> > +.BR PR_SVE_GET_VL ,
> > +.BR PR_SVE_SET_VL ,
> >  .BR PR_GET_THP_DISABLE ,
> >  .BR PR_GET_TIMING ,
> >  .BR PR_GET_TIMERSLACK ,
> > @@ -1817,6 +1917,18 @@ and unused arguments to
> >  .BR prctl ()
> >  are not 0.
> >  .TP
> > +.B EINVAL
> > +.I option
> > +was
> > +.B PR_SVE_SET_VL
> > +and
> > +.I arg2
> > +contains invalid flags, or
> > +.I arg2
> > +&
> > +.B SVE_VL_LEN_MASK
> > +is not a valid vector length.
> > +.TP
> 
> PR_SVE_GET_VL can return -EINVAL if SVE is not supported.

See the earlier patch about the "unsupported hardware case of EINVAL".

This affects many prctls, is "obvious" and we'd just have to document
the same thing over and over again...


Thanks for the review.  Perhaps I was slightly oo hasty about having got
it half right!

---Dave

Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)

[Michael Kerrisk (man-pages)]

Hi,

On 5/13/20 12:46 PM, Dave Martin wrote:
> On Wed, May 13, 2020 at 09:43:52AM +0100, Will Deacon wrote:
>> Hi Dave,
>>
>> On Tue, May 12, 2020 at 05:36:58PM +0100, Dave Martin wrote:
>>> diff --git a/man2/prctl.2 b/man2/prctl.2
>>> index 7f511d2..dd16227 100644
>>> --- a/man2/prctl.2
>>> +++ b/man2/prctl.2
>>> @@ -1291,6 +1291,104 @@ call failing with the error
>>>  .BR ENXIO .
>>>  For further details, see the kernel source file
>>>  .IR Documentation/admin-guide/kernel-parameters.txt .
>>> +.\" prctl PR_SVE_SET_VL
>>> +.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
>>> +.\" linux-5.6/Documentation/arm64/sve.rst
>>> +.TP
>>> +.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
>>> +Configure the thread's SVE vector length,
>>> +as specified by
>>> +.IR arg2 .
>>> +Arguments
>>> +.IR arg3 ", " arg4 " and " arg5
>>> +are ignored.
>>
>> Bugger, did we forget to force these to zero? I guess we should write the
>> man-page first next time :(

Quite...

> Not an accident, but there does seem to be some inconsistency in policy
> among the various prctls here.

The whole 5-args-for-prctl thing was a bit of a misdesign.

The general preference is that, for new prctls, unused arguments 
should be required to be zero. Historically, there was much
inconsistency.

> glibc explicitly has
> 
> 	extern int prctl (int __option, ...);
> 
> (and nobody has to write _exit(0, 0, 0, 0, 0, 0) after all.)
> 
> Is there some agreed rationale for requiring redundant arguments to be
> supplied explicitly as zero?  For now there are likely to be few users
> of this, so we _might_ get away with changing the behaviour here if it's
> considered important enough.

See above.

> There is no forwards compatibility problem with this prctl though,
> because there are spare bits in arg2 which can "turn on" additional
> args if needed.
> 
> Also, it's implausible that PR_SVE_GET_VL will ever want an argument.
> 
> There are still 2 billion unallocated prctl numbers, so new prctls can
> always be added if there's ever a need to work around these limitations,
> but it seems extremely unlikely.
> 
>>
>>> +.IP
>>> +The bits of
>>> +.I arg2
>>> +corresponding to
>>> +.B SVE_VL_LEN_MASK
>>
>> PR_SVE_LEN_MASK
> 
> Hmm, not sure how that happened.  Good spot!
> 
> I'll recheck that all the names are real when reposting.
> 
>>> +must be set to the desired vector length in bytes.
>>> +In addition,
>>> +.I arg2
>>> +may include zero or more of the following flags:
>>> +.RS
>>> +.TP
>>> +.B PR_SVE_VL_INHERIT
>>> +Inherit the configured vector length across
>>> +.BR execve (2).
>>> +.TP
>>> +.B PR_SVE_SET_VL_ONEXEC
>>> +Defer the change until the next
>>> +.BR execve (2)
>>> +in this thread.
>>
>> (aside, it's weird that we didn't allocate (1<<16) for one of these flags)
> 
> The flag definitions are shared with ptrace: ptrace is the
> SVE_PT_REGS_SVE format selection bit, which isn't relevant to the prctl.
> 
> Maybe it would have made more sense to keep the definitions completely
> separate, but it's there now.
> 
>>> +If
>>> +.B PR_SVE_VL_INHERIT
>>> +is also included in
>>> +.IR arg2 ,
>>> +it takes effect
>>> +.I after
>>> +this deferred change.
>>
>> I find this a bit hard to follow, since it's not clear to me whether the
>> INHERIT flag is effectively set before or after the next execve(). In other
>> words, if both PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT are specified,
>> is the vector length preserved or reset on the next execve()?
> 
> It makes no difference, because the ONEXEC handling takes priority over
> the INHERIT handling. But either way INHERIT is never cleared by execve()
> and will apply at subsequent execs().
> 
> Explaining all this properly seems out of scope here.  Maybe this should
> be trimmed down rather than elaborated?  Or perhaps just explain it in
> terms of what the kernel does instead of futile attempts to make it
> intuitive?
> 
> Ultimately I'll probably write a separate page or pages for SVE and other
> arm64 specifics.

(okay.)

>>> +.RE
>>> +.IP
>>> +On success, the vector length and flags are set as requested,
>>> +and any deferred change that was pending immediately before the
>>> +.B PR_SVE_SET_VL
>>> +call is canceled.
>>
>> Huh, turns out 'canceled' is a valid US spelling. Fair enough, but it looks
>> wrong to me ;)
> 
> Yeah, I know, but the man pages do have a documented policy on this...
> 
> prctl.2 has a lot of authors, so having mixed spellings could get
> particularly messy.

Quite. Indeed, that was how things were when I took over as
maintainer: a hodge-podge of British and American spellings,
occasionally even in the same page. I decided we needed
consistency, and though American is not my native spelling,
it seemed the most appropriate convention.

>>
>>> +If
>>> +.B PR_SVE_SET_VL_ONEXEC
>>> +was included in
>>> +.IR arg2 ,
>>> +the returned value describes the configuration
>>> +scheduled to take effect at the next
>>> +.BR execve (2).
>>
>> "describes the configuration" how?
>>
>>> +Otherwise, the effect is immediate and
>>> +the returned value describes the new configuration.
>>> +The returned value is encoded in the same way as the return value of
>>> +.BR PR_SVE_GET_VL .
>>
>> Aha. Maybe move this bit up slightly?
> 
> Yes, I'll reorder that.
> 
>>
>>> +.IP
>>> +If neither of the above flags is included in
>>
>> are included
> 
> Debatable.
> 
> The subject of the verb here is not "flags" (plural), but "neither of
> the above flags" (which is more nuanced, though it can be interpreted
> as singular).  Usage varies, and I don't consider this wrong.

As far as I know, the grammarians are with you on this one,
Dave, and if I was writing carefully, I'd do the same as you.
But, the plural here is also frequent (and so common that I would
hesitate to call it "wrong").

[...]


Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)

[Dave Martin]

On Wed, May 13, 2020 at 01:01:12PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi,
> 
> On 5/13/20 12:46 PM, Dave Martin wrote:
> > On Wed, May 13, 2020 at 09:43:52AM +0100, Will Deacon wrote:
> >> Hi Dave,
> >>
> >> On Tue, May 12, 2020 at 05:36:58PM +0100, Dave Martin wrote:
> >>> diff --git a/man2/prctl.2 b/man2/prctl.2
> >>> index 7f511d2..dd16227 100644
> >>> --- a/man2/prctl.2
> >>> +++ b/man2/prctl.2
> >>> @@ -1291,6 +1291,104 @@ call failing with the error
> >>>  .BR ENXIO .
> >>>  For further details, see the kernel source file
> >>>  .IR Documentation/admin-guide/kernel-parameters.txt .
> >>> +.\" prctl PR_SVE_SET_VL
> >>> +.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
> >>> +.\" linux-5.6/Documentation/arm64/sve.rst
> >>> +.TP
> >>> +.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
> >>> +Configure the thread's SVE vector length,
> >>> +as specified by
> >>> +.IR arg2 .
> >>> +Arguments
> >>> +.IR arg3 ", " arg4 " and " arg5
> >>> +are ignored.
> >>
> >> Bugger, did we forget to force these to zero? I guess we should write the
> >> man-page first next time :(
> 
> Quite...
> 
> > Not an accident, but there does seem to be some inconsistency in policy
> > among the various prctls here.
> 
> The whole 5-args-for-prctl thing was a bit of a misdesign.
> 
> The general preference is that, for new prctls, unused arguments 
> should be required to be zero. Historically, there was much
> inconsistency.
> 
> > glibc explicitly has
> > 
> > 	extern int prctl (int __option, ...);
> > 
> > (and nobody has to write _exit(0, 0, 0, 0, 0, 0) after all.)
> > 
> > Is there some agreed rationale for requiring redundant arguments to be
> > supplied explicitly as zero?  For now there are likely to be few users
> > of this, so we _might_ get away with changing the behaviour here if it's
> > considered important enough.
> 
> See above.

So there is no bulletproof rationale for either approach, but the main
concern is inconsistency?  Have I understood that right?

I'll propose to get that written down in the kernel source somewhere
if so.

(From my end, the pros and cons of the two approaches seem superficial
but the inconsistency is indeed annoying.  For PR_SVE_SET_VL, I think
the first example I looked at didn't zero the trailing arguments, so I
didn't either... but it's been upstream for several releases, so most
likely we're stuck with it.)

> 
> > There is no forwards compatibility problem with this prctl though,
> > because there are spare bits in arg2 which can "turn on" additional
> > args if needed.
> > 
> > Also, it's implausible that PR_SVE_GET_VL will ever want an argument.
> > 
> > There are still 2 billion unallocated prctl numbers, so new prctls can
> > always be added if there's ever a need to work around these limitations,
> > but it seems extremely unlikely.
> > 
> >>
> >>> +.IP
> >>> +The bits of
> >>> +.I arg2
> >>> +corresponding to
> >>> +.B SVE_VL_LEN_MASK
> >>
> >> PR_SVE_LEN_MASK
> > 
> > Hmm, not sure how that happened.  Good spot!
> > 
> > I'll recheck that all the names are real when reposting.
> > 
> >>> +must be set to the desired vector length in bytes.
> >>> +In addition,
> >>> +.I arg2
> >>> +may include zero or more of the following flags:
> >>> +.RS
> >>> +.TP
> >>> +.B PR_SVE_VL_INHERIT
> >>> +Inherit the configured vector length across
> >>> +.BR execve (2).
> >>> +.TP
> >>> +.B PR_SVE_SET_VL_ONEXEC
> >>> +Defer the change until the next
> >>> +.BR execve (2)
> >>> +in this thread.
> >>
> >> (aside, it's weird that we didn't allocate (1<<16) for one of these flags)
> > 
> > The flag definitions are shared with ptrace: ptrace is the
> > SVE_PT_REGS_SVE format selection bit, which isn't relevant to the prctl.
> > 
> > Maybe it would have made more sense to keep the definitions completely
> > separate, but it's there now.
> > 
> >>> +If
> >>> +.B PR_SVE_VL_INHERIT
> >>> +is also included in
> >>> +.IR arg2 ,
> >>> +it takes effect
> >>> +.I after
> >>> +this deferred change.
> >>
> >> I find this a bit hard to follow, since it's not clear to me whether the
> >> INHERIT flag is effectively set before or after the next execve(). In other
> >> words, if both PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT are specified,
> >> is the vector length preserved or reset on the next execve()?
> > 
> > It makes no difference, because the ONEXEC handling takes priority over
> > the INHERIT handling. But either way INHERIT is never cleared by execve()
> > and will apply at subsequent execs().
> > 
> > Explaining all this properly seems out of scope here.  Maybe this should
> > be trimmed down rather than elaborated?  Or perhaps just explain it in
> > terms of what the kernel does instead of futile attempts to make it
> > intuitive?
> > 
> > Ultimately I'll probably write a separate page or pages for SVE and other
> > arm64 specifics.
> 
> (okay.)
> 
> >>> +.RE
> >>> +.IP
> >>> +On success, the vector length and flags are set as requested,
> >>> +and any deferred change that was pending immediately before the
> >>> +.B PR_SVE_SET_VL
> >>> +call is canceled.
> >>
> >> Huh, turns out 'canceled' is a valid US spelling. Fair enough, but it looks
> >> wrong to me ;)
> > 
> > Yeah, I know, but the man pages do have a documented policy on this...
> > 
> > prctl.2 has a lot of authors, so having mixed spellings could get
> > particularly messy.
> 
> Quite. Indeed, that was how things were when I took over as
> maintainer: a hodge-podge of British and American spellings,
> occasionally even in the same page. I decided we needed
> consistency, and though American is not my native spelling,
> it seemed the most appropriate convention.
> 
> >>
> >>> +If
> >>> +.B PR_SVE_SET_VL_ONEXEC
> >>> +was included in
> >>> +.IR arg2 ,
> >>> +the returned value describes the configuration
> >>> +scheduled to take effect at the next
> >>> +.BR execve (2).
> >>
> >> "describes the configuration" how?
> >>
> >>> +Otherwise, the effect is immediate and
> >>> +the returned value describes the new configuration.
> >>> +The returned value is encoded in the same way as the return value of
> >>> +.BR PR_SVE_GET_VL .
> >>
> >> Aha. Maybe move this bit up slightly?
> > 
> > Yes, I'll reorder that.
> > 
> >>
> >>> +.IP
> >>> +If neither of the above flags is included in
> >>
> >> are included
> > 
> > Debatable.
> > 
> > The subject of the verb here is not "flags" (plural), but "neither of
> > the above flags" (which is more nuanced, though it can be interpreted
> > as singular).  Usage varies, and I don't consider this wrong.
> 
> As far as I know, the grammarians are with you on this one,
> Dave, and if I was writing carefully, I'd do the same as you.

Good, because I just made that up to justify myself!

> But, the plural here is also frequent (and so common that I would
> hesitate to call it "wrong").

Sure, I don't think either is wrong as such.  My preference is only a
preference, and partly depends on the context anyway.

Cheers
---Dave

Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)

[Will Deacon]

On Wed, May 13, 2020 at 03:02:00PM +0100, Dave Martin wrote:
> On Wed, May 13, 2020 at 01:01:12PM +0200, Michael Kerrisk (man-pages) wrote:
> > On 5/13/20 12:46 PM, Dave Martin wrote:
> > > On Wed, May 13, 2020 at 09:43:52AM +0100, Will Deacon wrote:
> > >> On Tue, May 12, 2020 at 05:36:58PM +0100, Dave Martin wrote:
> > > glibc explicitly has
> > > 
> > > 	extern int prctl (int __option, ...);
> > > 
> > > (and nobody has to write _exit(0, 0, 0, 0, 0, 0) after all.)
> > > 
> > > Is there some agreed rationale for requiring redundant arguments to be
> > > supplied explicitly as zero?  For now there are likely to be few users
> > > of this, so we _might_ get away with changing the behaviour here if it's
> > > considered important enough.
> > 
> > See above.
> 
> So there is no bulletproof rationale for either approach, but the main
> concern is inconsistency?  Have I understood that right?

I think it's all just an extension of "make sure unused parameters are 0"
idiom which allows those bits to be safely repurposed for flags and things
later on without the worry of existing applications getting away with
passing junk.

> I'll propose to get that written down in the kernel source somewhere
> if so.

That would be a really good idea, actually!

> (From my end, the pros and cons of the two approaches seem superficial
> but the inconsistency is indeed annoying.  For PR_SVE_SET_VL, I think
> the first example I looked at didn't zero the trailing arguments, so I
> didn't either... but it's been upstream for several releases, so most
> likely we're stuck with it.)

FWIW, I wasn't blaming you for this. Just that these oversights aren't
always apparent when reviewing patches, but become more clear when
reviewing the documentation.

> > > There is no forwards compatibility problem with this prctl though,
> > > because there are spare bits in arg2 which can "turn on" additional
> > > args if needed.
> > > 
> > > Also, it's implausible that PR_SVE_GET_VL will ever want an argument.
> > > 
> > > There are still 2 billion unallocated prctl numbers, so new prctls can
> > > always be added if there's ever a need to work around these limitations,
> > > but it seems extremely unlikely.

Oh, there are ways out, but had I noticed this during code review it
would've been very easy just to enforce zero for the other args and be done
with it.

> > >>> +If
> > >>> +.B PR_SVE_VL_INHERIT
> > >>> +is also included in
> > >>> +.IR arg2 ,
> > >>> +it takes effect
> > >>> +.I after
> > >>> +this deferred change.
> > >>
> > >> I find this a bit hard to follow, since it's not clear to me whether the
> > >> INHERIT flag is effectively set before or after the next execve(). In other
> > >> words, if both PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT are specified,
> > >> is the vector length preserved or reset on the next execve()?
> > > 
> > > It makes no difference, because the ONEXEC handling takes priority over
> > > the INHERIT handling. But either way INHERIT is never cleared by execve()
> > > and will apply at subsequent execs().
> > > 
> > > Explaining all this properly seems out of scope here.  Maybe this should
> > > be trimmed down rather than elaborated?  Or perhaps just explain it in
> > > terms of what the kernel does instead of futile attempts to make it
> > > intuitive?

Hmm, if we don't explain it in the man page then we should at least point
people to somewhere where they can get the gory details, because I think
they're necessary in order to use the prctl() request correctly. I'm still
not confident that I understand the semantics of setting both
PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT without reading the code, which
may change.

(I concede on all the spelling/grammar discussions ;)

Will

Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)

[Dave Martin]

On Wed, May 13, 2020 at 10:11:54PM +0100, Will Deacon wrote:
> On Wed, May 13, 2020 at 03:02:00PM +0100, Dave Martin wrote:
> > On Wed, May 13, 2020 at 01:01:12PM +0200, Michael Kerrisk (man-pages) wrote:
> > > On 5/13/20 12:46 PM, Dave Martin wrote:
> > > > On Wed, May 13, 2020 at 09:43:52AM +0100, Will Deacon wrote:
> > > >> On Tue, May 12, 2020 at 05:36:58PM +0100, Dave Martin wrote:
> > > > glibc explicitly has
> > > > 
> > > > 	extern int prctl (int __option, ...);
> > > > 
> > > > (and nobody has to write _exit(0, 0, 0, 0, 0, 0) after all.)
> > > > 
> > > > Is there some agreed rationale for requiring redundant arguments to be
> > > > supplied explicitly as zero?  For now there are likely to be few users
> > > > of this, so we _might_ get away with changing the behaviour here if it's
> > > > considered important enough.
> > > 
> > > See above.
> > 
> > So there is no bulletproof rationale for either approach, but the main
> > concern is inconsistency?  Have I understood that right?
> 
> I think it's all just an extension of "make sure unused parameters are 0"
> idiom which allows those bits to be safely repurposed for flags and things
> later on without the worry of existing applications getting away with
> passing junk.

I'd say that the explicit zeroing may give a false sense of safety, but
I sympathise with the intent.

At least, I think the explicit zeroing means that any resulting bugs are
more likely to be fixable in userspace.

> > I'll propose to get that written down in the kernel source somewhere
> > if so.
> 
> That would be a really good idea, actually!
> 
> > (From my end, the pros and cons of the two approaches seem superficial
> > but the inconsistency is indeed annoying.  For PR_SVE_SET_VL, I think
> > the first example I looked at didn't zero the trailing arguments, so I
> > didn't either... but it's been upstream for several releases, so most
> > likely we're stuck with it.)
> 
> FWIW, I wasn't blaming you for this. Just that these oversights aren't
> always apparent when reviewing patches, but become more clear when
> reviewing the documentation.

I'll have a think, so long as nobody implies that the SVE prctls are
"wrong" ;)

Adding comments in the code about how the implementation of those prctls
can and can't safely be extended would be sensible though.  I'll try to
address that at some point.

> > > > There is no forwards compatibility problem with this prctl though,
> > > > because there are spare bits in arg2 which can "turn on" additional
> > > > args if needed.
> > > > 
> > > > Also, it's implausible that PR_SVE_GET_VL will ever want an argument.
> > > > 
> > > > There are still 2 billion unallocated prctl numbers, so new prctls can
> > > > always be added if there's ever a need to work around these limitations,
> > > > but it seems extremely unlikely.
> 
> Oh, there are ways out, but had I noticed this during code review it
> would've been very easy just to enforce zero for the other args and be done
> with it.

Ack

> > > >>> +If
> > > >>> +.B PR_SVE_VL_INHERIT
> > > >>> +is also included in
> > > >>> +.IR arg2 ,
> > > >>> +it takes effect
> > > >>> +.I after
> > > >>> +this deferred change.
> > > >>
> > > >> I find this a bit hard to follow, since it's not clear to me whether the
> > > >> INHERIT flag is effectively set before or after the next execve(). In other
> > > >> words, if both PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT are specified,
> > > >> is the vector length preserved or reset on the next execve()?
> > > > 
> > > > It makes no difference, because the ONEXEC handling takes priority over
> > > > the INHERIT handling. But either way INHERIT is never cleared by execve()
> > > > and will apply at subsequent execs().
> > > > 
> > > > Explaining all this properly seems out of scope here.  Maybe this should
> > > > be trimmed down rather than elaborated?  Or perhaps just explain it in
> > > > terms of what the kernel does instead of futile attempts to make it
> > > > intuitive?
> 
> Hmm, if we don't explain it in the man page then we should at least point
> people to somewhere where they can get the gory details, because I think
> they're necessary in order to use the prctl() request correctly. I'm still
> not confident that I understand the semantics of setting both
> PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT without reading the code, which
> may change.
> 
> (I concede on all the spelling/grammar discussions ;)

Ultimately I aim to add another page, but for now would it be sufficient
to refer to Documentation/?

Cheers
---Dave

Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)

[Dave Martin]

On Wed, May 13, 2020 at 10:11:54PM +0100, Will Deacon wrote:
> On Wed, May 13, 2020 at 03:02:00PM +0100, Dave Martin wrote:
> > On Wed, May 13, 2020 at 01:01:12PM +0200, Michael Kerrisk (man-pages) wrote:
> > > On 5/13/20 12:46 PM, Dave Martin wrote:
> > > > On Wed, May 13, 2020 at 09:43:52AM +0100, Will Deacon wrote:
> > > >> On Tue, May 12, 2020 at 05:36:58PM +0100, Dave Martin wrote:

[...]

> > > >>> +If
> > > >>> +.B PR_SVE_VL_INHERIT
> > > >>> +is also included in
> > > >>> +.IR arg2 ,
> > > >>> +it takes effect
> > > >>> +.I after
> > > >>> +this deferred change.
> > > >>
> > > >> I find this a bit hard to follow, since it's not clear to me whether the
> > > >> INHERIT flag is effectively set before or after the next execve(). In other
> > > >> words, if both PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT are specified,
> > > >> is the vector length preserved or reset on the next execve()?
> > > > 
> > > > It makes no difference, because the ONEXEC handling takes priority over
> > > > the INHERIT handling. But either way INHERIT is never cleared by execve()
> > > > and will apply at subsequent execs().
> > > > 
> > > > Explaining all this properly seems out of scope here.  Maybe this should
> > > > be trimmed down rather than elaborated?  Or perhaps just explain it in
> > > > terms of what the kernel does instead of futile attempts to make it
> > > > intuitive?
> 
> Hmm, if we don't explain it in the man page then we should at least point
> people to somewhere where they can get the gory details, because I think
> they're necessary in order to use the prctl() request correctly. I'm still
> not confident that I understand the semantics of setting both
> PR_SVE_SET_VL_ONEXEC and PR_SVE_VL_INHERIT without reading the code, which
> may change.

On this point, can you review the following wording?

I simply enumerate the possible flag combinations now, rather than tying
myself in knots trying to describe the two flags independently.

Cheers
---Dave

--8<--

       PR_SVE_SET_VL (since Linux 4.15, only on arm64)
              Configure the thread's SVE vector length, as specified by  (int)
              arg2.  Arguments arg3, arg4 and arg5 are ignored.

              The bits of arg2 corresponding to PR_SVE_VL_LEN_MASK must be set
              to the desired vector length in bytes.  This is  interpreted  as
              an  upper  bound:  the kernel will select the greatest available
              vector length that does not exceed the value specified.  In par-
              ticular,  specifying  SVE_VL_MAX (defined in <asm/sigcontext.h>)
              for the PR_SVE_VL_LEN_MASK bits requests the  maximum  supported
              vector length.

              In  addition,  arg2  may  include  the following combinations of
              flags:

              0      Perform the change immediately.  At the next execve(2) in
                     the  thread, the vector length will be reset to the value
                     configured in /proc/sys/abi/sve_default_vector_length.

              PR_SVE_VL_INHERIT
                     Perform the  change  immediately.   Subsequent  execve(2)
                     calls will preserve the new vector length.

              PR_SVE_SET_VL_ONEXEC
                     Defer  the  change,  so  that it is performed at the next
                     execve(2) in the thread.  Further  execve(2)  calls  will
                     reset  the  vector  length  to  the  value  configured in
                     /proc/sys/abi/sve_default_vector_length.

              PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT
                     Defer the change, so that it is  performed  at  the  next
                     execve(2)  in  the  thread.  Further execve(2) calls will
                     preserve the new vector length.

              In all cases, any previously pending  deferred  change  is  can-
              celed.

              The  call fails with error EINVAL if SVE is not supported on the
              platform, if arg2 is unrecognized or invalid, or  the  value  in
              the  bits of arg2 corresponding to PR_SVE_VL_LEN_MASK is outside
              the range SVE_VL_MIN..SVE_VL_MAX, or is not a multiple of 16.

              On success, a nonnegative value is returned that  describes  the
              selected  configuration,  which may differ from the current con-
              figuration if PR_SVE_SET_VL_ONEXEC was specified.  The value  is
              encoded in the same way as the return value of PR_SVE_GET_VL.

              The  configuration  (including  any  pending deferred change) is
              inherited across fork(2) and clone(2).

              For more information, see  the  kernel  source  file  Documenta-
              tion/arm64/sve.rst  (or Documentation/arm64/sve.txt before Linux
              5.3).

              Warning: Because the compiler or  run-time  environment  may  be
              using SVE, using this call without the PR_SVE_SET_VL_ONEXEC flag
              can lead to unpredicable behaviour in the calling process.   The
              conditions for using it safely are complex and system-dependent.
              Don't use it unless you really know what you are doing.

-->8--

[PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)

[Dave Martin]

Add documentation for the PR_PAC_RESET_KEYS ioctl added in Linux
5.0 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Will Deacon <will@kernel.org>
Cc: Catalin Marinas <catalin.marinas@arm.com>
Cc: Amit Daniel Kachhap <amit.kachhap@arm.com>
Cc: Mark Rutland <mark.rutland@arm.com>

---

Note that the comment about PR_PAC_RESET_KEYS(0) being the recommended
way to set up a fresh execution context is not present in the existing
kernel documentation.

I vaguely remember some discussion to this effect; in any case, it seems
sensible, given that there must have been _some_ rationale for this
feature...  Shout if it sounds wrong!
---
 man2/prctl.2 | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index dd16227..7ea60e2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -950,6 +950,46 @@ behavior.
 A value of 1 indicates
 .BR execve (2)
 will operate in the privilege-restricting mode described above.
+.\" prctl PR_PAC_RESET_KEYS
+.\" commit ba830885656414101b2f8ca88786524d4bb5e8c1
+.TP
+.BR PR_PAC_RESET_KEYS " (since Linux 5.0, only on arm64)"
+Securely reset the thread's pointer authentication keys
+to fresh random values generated by the kernel.
+.IP
+The set of keys to be reset is specified by
+.IR arg2 ,
+which must be a logical OR of zero or more of the following:
+.RS
+.TP
+.B PR_PAC_APIAKEY
+instruction authentication key A
+.TP
+.B PR_PAC_APIBKEY
+instruction authentication key B
+.TP
+.B PR_PAC_APDAKEY
+data authentication key A
+.TP
+.B PR_PAC_APDBKEY
+data authentication key B
+.TP
+.B PR_PAC_APGAKEY
+generic authentication \(lqA\(rq key.
+.IP
+(Yes folks, there really is no generic B key.)
+.RE
+.IP
+As a special case, if
+.I arg2
+is zero then all the keys are reset.
+Since new keys could be added in future,
+this is the recommended way to completely wipe the existing keys
+when creating a new execution context.
+.IP
+The remaining arguments
+.IR arg3 ", " arg4 " and " arg5
+must all be zero.
 .\" prctl PR_SET_PDEATHSIG
 .TP
 .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
@@ -1920,6 +1960,27 @@ are not 0.
 .B EINVAL
 .I option
 was
+.B PR_PAC_RESET_KEYS
+and
+.I arg2
+contains non-zero bits other than
+.BR
+.BR PR_PAC_APIAKEY ,
+.BR PR_PAC_APIBKEY ,
+.BR PR_PAC_APDAKEY ,
+.B PR_PAC_APDBKEY
+and
+.BR PR_PAC_APGAKEY ;
+or
+.IR arg3 ,
+.I arg4
+and
+.I arg5
+were not all zero.
+.TP
+.B EINVAL
+.I option
+was
 .B PR_SVE_SET_VL
 and
 .I arg2
-- 
2.1.4

Re: [PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)

[Will Deacon]

Hi Dave,

On Tue, May 12, 2020 at 05:36:59PM +0100, Dave Martin wrote:
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index dd16227..7ea60e2 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -950,6 +950,46 @@ behavior.
>  A value of 1 indicates
>  .BR execve (2)
>  will operate in the privilege-restricting mode described above.
> +.\" prctl PR_PAC_RESET_KEYS
> +.\" commit ba830885656414101b2f8ca88786524d4bb5e8c1
> +.TP
> +.BR PR_PAC_RESET_KEYS " (since Linux 5.0, only on arm64)"
> +Securely reset the thread's pointer authentication keys
> +to fresh random values generated by the kernel.
> +.IP
> +The set of keys to be reset is specified by
> +.IR arg2 ,
> +which must be a logical OR of zero or more of the following:
> +.RS
> +.TP
> +.B PR_PAC_APIAKEY
> +instruction authentication key A
> +.TP
> +.B PR_PAC_APIBKEY
> +instruction authentication key B
> +.TP
> +.B PR_PAC_APDAKEY
> +data authentication key A
> +.TP
> +.B PR_PAC_APDBKEY
> +data authentication key B
> +.TP
> +.B PR_PAC_APGAKEY
> +generic authentication \(lqA\(rq key.
> +.IP
> +(Yes folks, there really is no generic B key.)
> +.RE
> +.IP
> +As a special case, if
> +.I arg2
> +is zero then all the keys are reset.
> +Since new keys could be added in future,
> +this is the recommended way to completely wipe the existing keys
> +when creating a new execution context.

I see what you're saying, but the keys are also reset on exec() iirc, so we
don't want to encourage people to issue the prctl() unnecessarily
immediately following an exec().

> +.IP
> +The remaining arguments
> +.IR arg3 ", " arg4 " and " arg5
> +must all be zero.
>  .\" prctl PR_SET_PDEATHSIG
>  .TP
>  .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
> @@ -1920,6 +1960,27 @@ are not 0.
>  .B EINVAL
>  .I option
>  was
> +.B PR_PAC_RESET_KEYS
> +and
> +.I arg2
> +contains non-zero bits other than
> +.BR
> +.BR PR_PAC_APIAKEY ,
> +.BR PR_PAC_APIBKEY ,
> +.BR PR_PAC_APDAKEY ,
> +.B PR_PAC_APDBKEY
> +and
> +.BR PR_PAC_APGAKEY ;
> +or
> +.IR arg3 ,
> +.I arg4
> +and
> +.I arg5
> +were not all zero.

Do we care about other reasons for -EINVAL, such as the system not
supporting pointer authentication?

Will

Re: [PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)

[Dave Martin]

On Wed, May 13, 2020 at 08:25:31AM +0100, Will Deacon wrote:
> Hi Dave,
> 
> On Tue, May 12, 2020 at 05:36:59PM +0100, Dave Martin wrote:
> > diff --git a/man2/prctl.2 b/man2/prctl.2
> > index dd16227..7ea60e2 100644
> > --- a/man2/prctl.2
> > +++ b/man2/prctl.2
> > @@ -950,6 +950,46 @@ behavior.
> >  A value of 1 indicates
> >  .BR execve (2)
> >  will operate in the privilege-restricting mode described above.
> > +.\" prctl PR_PAC_RESET_KEYS
> > +.\" commit ba830885656414101b2f8ca88786524d4bb5e8c1
> > +.TP
> > +.BR PR_PAC_RESET_KEYS " (since Linux 5.0, only on arm64)"
> > +Securely reset the thread's pointer authentication keys
> > +to fresh random values generated by the kernel.
> > +.IP
> > +The set of keys to be reset is specified by
> > +.IR arg2 ,
> > +which must be a logical OR of zero or more of the following:
> > +.RS
> > +.TP
> > +.B PR_PAC_APIAKEY
> > +instruction authentication key A
> > +.TP
> > +.B PR_PAC_APIBKEY
> > +instruction authentication key B
> > +.TP
> > +.B PR_PAC_APDAKEY
> > +data authentication key A
> > +.TP
> > +.B PR_PAC_APDBKEY
> > +data authentication key B
> > +.TP
> > +.B PR_PAC_APGAKEY
> > +generic authentication \(lqA\(rq key.
> > +.IP
> > +(Yes folks, there really is no generic B key.)
> > +.RE
> > +.IP
> > +As a special case, if
> > +.I arg2
> > +is zero then all the keys are reset.
> > +Since new keys could be added in future,
> > +this is the recommended way to completely wipe the existing keys
> > +when creating a new execution context.
> 
> I see what you're saying, but the keys are also reset on exec() iirc, so we
> don't want to encourage people to issue the prctl() unnecessarily
> immediately following an exec().

I thought of saying that, then pulled it out again.

How about:

"[...] a new execution context within an existing process.  Note that
execve() always resets all the keys as part of its operation, without
the need for this prctl() call.  PR_PAC_RESET_KEYS is intended for
custom situations that do not involve execve(), such as creating a new
managed run-time sandbox."

I deliberately don't say "thread" because that's probably libc's job.
I'll need to check glibc does, though.  There may be issues with
pthreads semantics that mean we can't reset the keys there.

> 
> > +.IP
> > +The remaining arguments
> > +.IR arg3 ", " arg4 " and " arg5
> > +must all be zero.
> >  .\" prctl PR_SET_PDEATHSIG
> >  .TP
> >  .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
> > @@ -1920,6 +1960,27 @@ are not 0.
> >  .B EINVAL
> >  .I option
> >  was
> > +.B PR_PAC_RESET_KEYS
> > +and
> > +.I arg2
> > +contains non-zero bits other than
> > +.BR
> > +.BR PR_PAC_APIAKEY ,
> > +.BR PR_PAC_APIBKEY ,
> > +.BR PR_PAC_APDAKEY ,
> > +.B PR_PAC_APDBKEY
> > +and
> > +.BR PR_PAC_APGAKEY ;
> > +or
> > +.IR arg3 ,
> > +.I arg4
> > +and
> > +.I arg5
> > +were not all zero.
> 
> Do we care about other reasons for -EINVAL, such as the system not
> supporting pointer authentication?

Again, I tried to catch that under the new "not supported by this
platform" wording in the earlier patch.  Do you think that's sufficient,
or do we need something else here?

Cheers
---Dave

Re: [PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)

[Will Deacon]

On Wed, May 13, 2020 at 03:36:54PM +0100, Dave Martin wrote:
> On Wed, May 13, 2020 at 08:25:31AM +0100, Will Deacon wrote:
> > On Tue, May 12, 2020 at 05:36:59PM +0100, Dave Martin wrote:
> > > +As a special case, if
> > > +.I arg2
> > > +is zero then all the keys are reset.
> > > +Since new keys could be added in future,
> > > +this is the recommended way to completely wipe the existing keys
> > > +when creating a new execution context.
> > 
> > I see what you're saying, but the keys are also reset on exec() iirc, so we
> > don't want to encourage people to issue the prctl() unnecessarily
> > immediately following an exec().
> 
> I thought of saying that, then pulled it out again.
> 
> How about:
> 
> "[...] a new execution context within an existing process.  Note that
> execve() always resets all the keys as part of its operation, without
> the need for this prctl() call.  PR_PAC_RESET_KEYS is intended for
> custom situations that do not involve execve(), such as creating a new
> managed run-time sandbox."
> 
> I deliberately don't say "thread" because that's probably libc's job.
> I'll need to check glibc does, though.  There may be issues with
> pthreads semantics that mean we can't reset the keys there.

That's better, but you may even be able to drop the "such as..." part, I
reckon.

> > > @@ -1920,6 +1960,27 @@ are not 0.
> > >  .B EINVAL
> > >  .I option
> > >  was
> > > +.B PR_PAC_RESET_KEYS
> > > +and
> > > +.I arg2
> > > +contains non-zero bits other than
> > > +.BR
> > > +.BR PR_PAC_APIAKEY ,
> > > +.BR PR_PAC_APIBKEY ,
> > > +.BR PR_PAC_APDAKEY ,
> > > +.B PR_PAC_APDBKEY
> > > +and
> > > +.BR PR_PAC_APGAKEY ;
> > > +or
> > > +.IR arg3 ,
> > > +.I arg4
> > > +and
> > > +.I arg5
> > > +were not all zero.
> > 
> > Do we care about other reasons for -EINVAL, such as the system not
> > supporting pointer authentication?
> 
> Again, I tried to catch that under the new "not supported by this
> platform" wording in the earlier patch.  Do you think that's sufficient,
> or do we need something else here?

As long as it's clear that the prctl() *can* fail and userspace can't just
ignore the return value, then I'm happy. If it's not obvious, then spelling
it out seems harmless to me.

Will

Re: [PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)

[Dave Martin]

On Wed, May 13, 2020 at 10:00:22PM +0100, Will Deacon wrote:
> On Wed, May 13, 2020 at 03:36:54PM +0100, Dave Martin wrote:
> > On Wed, May 13, 2020 at 08:25:31AM +0100, Will Deacon wrote:
> > > On Tue, May 12, 2020 at 05:36:59PM +0100, Dave Martin wrote:
> > > > +As a special case, if
> > > > +.I arg2
> > > > +is zero then all the keys are reset.
> > > > +Since new keys could be added in future,
> > > > +this is the recommended way to completely wipe the existing keys
> > > > +when creating a new execution context.
> > > 
> > > I see what you're saying, but the keys are also reset on exec() iirc, so we
> > > don't want to encourage people to issue the prctl() unnecessarily
> > > immediately following an exec().
> > 
> > I thought of saying that, then pulled it out again.
> > 
> > How about:
> > 
> > "[...] a new execution context within an existing process.  Note that
> > execve() always resets all the keys as part of its operation, without
> > the need for this prctl() call.  PR_PAC_RESET_KEYS is intended for
> > custom situations that do not involve execve(), such as creating a new
> > managed run-time sandbox."
> > 
> > I deliberately don't say "thread" because that's probably libc's job.
> > I'll need to check glibc does, though.  There may be issues with
> > pthreads semantics that mean we can't reset the keys there.
> 
> That's better, but you may even be able to drop the "such as..." part, I
> reckon.
> 
> > > > @@ -1920,6 +1960,27 @@ are not 0.
> > > >  .B EINVAL
> > > >  .I option
> > > >  was
> > > > +.B PR_PAC_RESET_KEYS
> > > > +and
> > > > +.I arg2
> > > > +contains non-zero bits other than
> > > > +.BR
> > > > +.BR PR_PAC_APIAKEY ,
> > > > +.BR PR_PAC_APIBKEY ,
> > > > +.BR PR_PAC_APDAKEY ,
> > > > +.B PR_PAC_APDBKEY
> > > > +and
> > > > +.BR PR_PAC_APGAKEY ;
> > > > +or
> > > > +.IR arg3 ,
> > > > +.I arg4
> > > > +and
> > > > +.I arg5
> > > > +were not all zero.
> > > 
> > > Do we care about other reasons for -EINVAL, such as the system not
> > > supporting pointer authentication?
> > 
> > Again, I tried to catch that under the new "not supported by this
> > platform" wording in the earlier patch.  Do you think that's sufficient,
> > or do we need something else here?
> 
> As long as it's clear that the prctl() *can* fail and userspace can't just
> ignore the return value, then I'm happy. If it's not obvious, then spelling
> it out seems harmless to me.

OK, I'll try to figure out a way to capture this.

Since prctl is really the wild west when it comes to error codes I was
presuming that's it's best to say nothing and rely on people's common sense.
But I guess this isn't great either.


How about summarising the key error cases here, and just putting a cross-
reference in the ERRORS section rather than trying to describe them
there?  I really don't want to duplicate this stuff -- that will get
unmaintanable, fast (if it hasn't already).

Cheers
---Dave

Re: [PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)

[Will Deacon]

On Mon, May 18, 2020 at 05:11:28PM +0100, Dave Martin wrote:
> How about summarising the key error cases here, and just putting a cross-
> reference in the ERRORS section rather than trying to describe them
> there?  I really don't want to duplicate this stuff -- that will get
> unmaintanable, fast (if it hasn't already).

Makes sense to me.

Will

Re: [PATCH 00/14] prctl.2 man page updates for Linux 5.6

[Michael Kerrisk (man-pages)]

Hi Dave,

On 5/12/20 6:36 PM, Dave Martin wrote:
> A bunch of updates to the prctl(2) man page to fill in the missing
> prctls (mostly) up to Linux 5.6 (along with a few other tweaks fixes).
> 
> People not Cc'd on the whole series can find the whole series at
> https://lore.kernel.org/linux-man/ .
> 
> Patches:
> 
>  * Patches 1-6 and 8-9 are rather trivial optional tweaks and fixes
>    that don't make substantive changes.  I can live with some of these
>    being dropped.
> 
>  * Patch 7 (removal of the MPX prctls) could use an Ack, but should be
>    uncontroversial.
> 
>  * Patches 10-11 cover recent extensions to the speculation control
>    prctls.
> 
>  * Patch 12 adds one particular case Errors for EINVAL, applicable to
>    all arch-specific prctls.  I've not tried too hard to be 100%
>    comprehensive with the error conditions, since the list in its
>    current form looks in need of a major overhaul.
> 
>  * Patches 13-14 add the new arm64-specific prctls.
>    (PR_SET_TAGGED_ADDR_CTRL requires a bit more discussion and will be
>    posted separately.)

Thanks. This is great!

> Maintainer notes:
> 
>  * I'm *asssuming* that the datestamps in .TH are automatically
>    updated by maintainer scripts, since maintaining them by hand would
>    interact very badly with rebase.  If needed I can go update them by
>    hand though.
> 
>  * Similarly, in the days of git (and because I see no recent entries)
>    I'm assuming that in-file changelogs no longer need to be updated.

Correct.

>    Again, I'm happy to do that if needed.

(No need.)

Except as noted below, patches have been applied:

> Dave Martin (14):
>   prctl.2: tfix clarify that prctl can apply to threads
>   prctl.2: Add health warning
>   prctl.2: tfix mis-description of thread ID values in procfs
>   prctl.2: srcfix add comments for navigation
>   prctl.2: tfix listing order of prctls
>   prctl.2: ffix quotation mark tweaks
>   prctl.2: Document removal of Intel MPX prctls
>   prctl.2: Work around bogus constant "maxsig" in PR_SET_PDEATHSIG
>   prctl.2: tfix minor punctuation in SPECULATION_CTRL prctls
>   prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls

Applied, but not yet pushed.

>   prctl.2: Add PR_SPEC_DISABLE_NOEXEC for SPECULATION_CTRL prctls

Applied, but not yet pushed.

>   prctl.2: Clarify the unsupported hardware case of EINVAL
>   prctl.2: Add SVE prctls (arm64)

Will had comments. I'm presuming there will be a v2 of this patch.

>   prctl.2: Add PR_PAC_RESET_KEYS (arm64)

Will had comments. I'm presuming there will be a v2 of this patch.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/