prctl.2 man page updates for Linux 5.6
Subsystems (2)
cover prctl.2 man page updates for Linux 5.6
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(-)
Signature · 1 line
2.1.4
A message that is not in the archive (sent off-list or not yet received): 1589301419-24459-1-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
PATCH 2/14 prctl.2: Add health warning
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.
--- man2/prctl.2 | 5 +++++ 1 file changed, 5 insertions(+)
man2/prctl.2 +5 -0
@@ -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
Signature · 1 line
2.1.4
A message that is not in the archive (sent off-list or not yet received): 1589301419-24459-3-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
Re: [PATCH 02/14] prctl.2: Add health warning
Hi Dave,
Quoted 6 lines · 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.
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
Quoted 22 lines
Signed-off-by Dave Martin <[email protected]>--- man2/prctl.2 | 5 +++++ 1 file changed, 5 insertions(+)man2/prctl.2 +5
-0@@ -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
Signature · 3 lines
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
Quoted 8 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 5 lines · 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.
Quoted 8 lines
Quoted 1 line
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
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 02/14] prctl.2: Add health warning
Hi Dave,
Quoted 18 lines · Dave Martin
Quoted 8 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 5 lines · 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.Quoted 8 lines
Quoted 1 line
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.
Quoted 2 lines
Certainly the "if at all" can go -- this was just a suggestion really.
Yes. Gone.
Quoted 2 lines
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.
Quoted 8 lines
The background to this patch is that things like the new
PR_PAC_RESET_KEYSandPR_SVE_SET_VLare 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.)
Quoted 8 lines
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
man2/prctl.2 +3 -3
@@ -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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
A message that is not in the archive (sent off-list or not yet received): 7218089f-20df-52b3-e1d4-ac63e0215efc-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Re: [PATCH 02/14] prctl.2: Add health warning
Quoted 48 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 18 lines · Dave Martin
Quoted 8 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 5 lines · 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.Quoted 8 lines
Quoted 1 line
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.
Quoted 2 lines
Certainly the "if at all" can go -- this was just a suggestion really.
Yes. Gone.
Quoted 2 lines
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.
Quoted 8 lines
The background to this patch is that things like the new
PR_PAC_RESET_KEYSandPR_SVE_SET_VLare 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.)
Quoted 6 lines
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.
Quoted 5 lines
Quoted 2 lines
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 5/14 prctl.2: tfix listing order of prctls
In reply to a message not in the archiveThe 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.
--- man2/prctl.2 | 138 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 69 insertions(+), 69 deletions(-)
man2/prctl.2 +69 -69
@@ -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.
Signature · 1 line
2.1.4
Re: [PATCH 05/14] prctl.2: tfix listing order of prctls
Hi Dave,
Quoted 6 lines · Dave Martin
The prctl list has historically been sorted by prctl name (ignoring any
SET_orGET_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.
Quoted 1 line
Content movement only. No semantic change.
And explicitly noting that detail is very helpful to me.
Patch applied.
Cheers,
Michael
Quoted 185 lines
Signed-off-by Dave Martin <[email protected]>--- man2/prctl.2 | 138 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 69 insertions(+), 69 deletions(-)man2/prctl.2 +69
-69@@ -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.
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
A message that is not in the archive (sent off-list or not yet received): 1bb991f4-176a-a74e-01fc-c73b49ed77f5-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Re: [PATCH 05/14] prctl.2: tfix listing order of prctls
Quoted 7 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 4 lines · Dave Martin
The prctl list has historically been sorted by prctl name (ignoring any
SET_orGET_prefix) to make individual prctls easier to find. Some noise seems to have crept in since.
Quoted 6 lines
Quoted 2 lines
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.
Quoted 4 lines
Quoted 2 lines
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
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 05/14] prctl.2: tfix listing order of prctls
Hi Dave,
Quoted 11 lines · Dave Martin
Quoted 10 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 6 lines · Dave Martin
The prctl list has historically been sorted by prctl name (ignoring any
SET_orGET_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.
Quoted 8 lines
Quoted 3 lines
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.
Quoted 2 lines
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.
Quoted 10 lines
If we split prctl.2 up with a fragment per prctl, we could paste the fragments together in the right order with a script.
Quoted 4 lines
Quoted 2 lines
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
Signature · 3 lines
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
Quoted 23 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 11 lines · Dave Martin
Quoted 10 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 6 lines · Dave Martin
The prctl list has historically been sorted by prctl name (ignoring any
SET_orGET_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.
Quoted 8 lines
Quoted 3 lines
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.
Quoted 8 lines
Quite.
Quoted 2 lines
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.
Quoted 7 lines
Quoted 7 lines
If we split prctl.2 up with a fragment per prctl, we could paste the fragments together in the right order with a script.
Quoted 3 lines
Quoted 2 lines
Content movement only. No semantic change.
Quoted 8 lines
Quoted 4 lines
Quoted 1 line
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 6/14 prctl.2: ffix quotation mark tweaks
In reply to a message not in the archiveConvert quote marks used for information terms in prose to use \(oq .. \(cq, for better graphical rendering.
---
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(-)
man2/prctl.2 +36 -35
@@ -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)).
Signature · 1 line
2.1.4
A message that is not in the archive (sent off-list or not yet received): 1589301419-24459-7-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
Re: [PATCH 06/14] prctl.2: ffix quotation mark tweaks
Hello Dave,
Quoted 4 lines · Dave Martin
Convert quote marks used for information terms in prose to use \(oq .. \(cq, for better graphical rendering.
Signed-off-by Dave Martin <[email protected]>
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.
Quoted 4 lines
---
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
Quoted 247 lines
In the C locale (or with -Tascii) the quotes still render as ' .
--- man2/prctl.2 | 71 ++++++++++++++++++++++++++++++------------------------------ 1 file changed, 36 insertions(+), 35 deletions(-)man2/prctl.2 +36
-35@@ -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)).
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
A message that is not in the archive (sent off-list or not yet received): 7afe32a5-9675-74d4-7c39-f1271d475afd-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Re: [PATCH 06/14] prctl.2: ffix quotation mark tweaks
Quoted 11 lines · Michael Kerrisk (man-pages)
Hello Dave,
Quoted 4 lines · Dave Martin
Convert quote marks used for information terms in prose to use \(oq .. \(cq, for better graphical rendering.
Signed-off-by Dave Martin <[email protected]>Again, this is a patch that I would prefer to see near the end of a series, rather than in the middle.
Quoted 6 lines
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).
Quoted 6 lines
Quoted 4 lines
---
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
Quoted 25 lines · Dave Martin
Quoted 11 lines · Michael Kerrisk (man-pages)
Hello Dave,
Quoted 4 lines · Dave Martin
Convert quote marks used for information terms in prose to use \(oq .. \(cq, for better graphical rendering.
Signed-off-by Dave Martin <[email protected]>Again, this is a patch that I would prefer to see near the end of a series, rather than in the middle.
Quoted 6 lines
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.
Quoted 6 lines
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.
Quoted 15 lines
Quoted 6 lines
Quoted 4 lines
---
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.
Quoted 4 lines
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.
Quoted 2 lines
(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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
A message that is not in the archive (sent off-list or not yet received): f575e35d-cd5e-5808-bed4-91bdfb9c2905-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Re: [PATCH 06/14] prctl.2: ffix quotation mark tweaks
Quoted 56 lines · Michael Kerrisk (man-pages)
Quoted 25 lines · Dave Martin
Quoted 11 lines · Michael Kerrisk (man-pages)
Hello Dave,
Quoted 4 lines · Dave Martin
Convert quote marks used for information terms in prose to use \(oq .. \(cq, for better graphical rendering.
Signed-off-by Dave Martin <[email protected]>Again, this is a patch that I would prefer to see near the end of a series, rather than in the middle.
Quoted 6 lines
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.
Quoted 6 lines
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.Quoted 15 lines
Quoted 6 lines
Quoted 4 lines
---
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.
Quoted 4 lines
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.
Quoted 6 lines
Thanks for the clarification.
Quoted 2 lines
(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 7/14 prctl.2: Document removal of Intel MPX prctls
In reply to a message not in the archiveThe Intel MPX API was removed from Linux 5.4. See Linux commit f240652b6032 ("x86/mpx: Remove MPX APIs")
Document this change.
--- man2/prctl.2 | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-)
man2/prctl.2 +7 -1
@@ -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-LXbPSdftPKxrdx17CPfAsdBPR1lH4CV8@public.gmane.org +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)"
Signature · 1 line
2.1.4
Re: [PATCH 07/14] prctl.2: Document removal of Intel MPX prctls
Quoted 4 lines · Dave Martin
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!
A message that is not in the archive (sent off-list or not yet received): 1589301419-24459-8-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
Re: [PATCH 07/14] prctl.2: Document removal of Intel MPX prctls
Quoted 4 lines · Dave Martin
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
Quoted 34 lines
Signed-off-by Dave Martin <[email protected]>Cc Dave Hansen <dave.hansen-VuQAYsv1563Yd54FQh9/[email protected]>Cc Thomas Gleixner <[email protected]>--- man2/prctl.2 | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-)man2/prctl.2 +7
-1@@ -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-LXbPSdftPKxrdx17CPfAsdBPR1lH4CV8@public.gmane.org +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)"
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH 9/14 prctl.2: tfix minor punctuation in SPECULATION_CTRL prctls
In reply to a message not in the archiveFix a few very minor bits of punctuation in PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.
--- man2/prctl.2 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
man2/prctl.2 +4 -4
@@ -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
Signature · 1 line
2.1.4
A message that is not in the archive (sent off-list or not yet received): 1589301419-24459-10-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
Re: [PATCH 09/14] prctl.2: tfix minor punctuation in SPECULATION_CTRL prctls
Quoted 4 lines · Dave Martin
Fix a few very minor bits of punctuation in
PR_SET_SPECULATION_CTRLandPR_GET_SPECULATION_CTRL.Signed-off-by Dave Martin <[email protected]>
Thanks, Dave. Patch applied.
Cheers,
Michael
Quoted 39 lines
--- man2/prctl.2 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)man2/prctl.2 +4
-4@@ -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
Signature · 3 lines
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
In reply to a message not in the archiveAdd the PR_SPEC_INDIRECT_BRANCH "misfeature" added in Linux 4.20 for PR_SET_SPECULATION_CTRL and PR_GET_SPECULATION_CTRL.
--- man2/prctl.2 | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-)
man2/prctl.2 +18 -6
@@ -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 .
Signature · 1 line
2.1.4
A message that is not in the archive (sent off-list or not yet received): 1589301419-24459-11-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
Re: [PATCH 10/14] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls
Hello Dave,
Quoted 6 lines · Dave Martin
Add the
PR_SPEC_INDIRECT_BRANCH"misfeature" added in Linux 4.20 forPR_SET_SPECULATION_CTRLandPR_GET_SPECULATION_CTRL.Signed-off-by Dave Martin <[email protected]>Cc Tim Chen <tim.c.chen-VuQAYsv1563Yd54FQh9/[email protected]>Cc Thomas Gleixner <[email protected]>
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.
Quoted 9 lines
--- man2/prctl.2 | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-)man2/prctl.2 +0
-0
man2/prctl.2 arguments must be specified as 0; otherwise the call fails with the error · line 1220
Quoted 10 lines
man2/prctl.2 +4
-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/
man2/prctl.2 arguments must be specified as 0; otherwise the call fails with the error · line 1224
Quoted 4 lines
man2/prctl.2 +4
-0+.\" commit 9137bb27e60e554dab694eafa4cca241fa3a694f +.TP +.BR PR_SPEC_INDIRECT_BRANCH " (since Linux 4.20)" +indirect branch speculation control.
s/indirect/enable indirect/
Quoted 19 lines
man2/prctl.2 +8
-3+.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
man2/prctl.2 Same as · line 1259
Quoted 10 lines
man2/prctl.2 +2
-1+.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
Signature · 3 lines
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
Quoted 37 lines · Michael Kerrisk (man-pages)
Hello Dave,
Quoted 6 lines · Dave Martin
Add the
PR_SPEC_INDIRECT_BRANCH"misfeature" added in Linux 4.20 forPR_SET_SPECULATION_CTRLandPR_GET_SPECULATION_CTRL.Signed-off-by Dave Martin <[email protected]>Cc Tim Chen <[email protected]>Cc Thomas Gleixner <[email protected]>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.
Quoted 9 lines
--- man2/prctl.2 | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-)man2/prctl.2 +0
-0man2/prctl.2 arguments must be specified as 0; otherwise the call fails with the error · line 1220
Quoted 10 lines
man2/prctl.2 +4
-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, ors/speculative/enable speculative/
Quoted 6 lines
man2/prctl.2 arguments must be specified as 0; otherwise the call fails with the error · line 1224
Quoted 4 lines
man2/prctl.2 +4
-0+.\" 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
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 10/14] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls
Quoted 38 lines · Dave Martin
Quoted 37 lines · Michael Kerrisk (man-pages)
Hello Dave,
Quoted 6 lines · Dave Martin
Add the
PR_SPEC_INDIRECT_BRANCH"misfeature" added in Linux 4.20 forPR_SET_SPECULATION_CTRLandPR_GET_SPECULATION_CTRL.Signed-off-by Dave Martin <[email protected]>Cc Tim Chen <tim.c.chen-VuQAYsv1563Yd54FQh9/[email protected]>Cc Thomas Gleixner <[email protected]>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.
Quoted 9 lines
--- man2/prctl.2 | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-)man2/prctl.2 +0
-0man2/prctl.2 arguments must be specified as 0; otherwise the call fails with the error · line 1220
Quoted 10 lines
man2/prctl.2 +4
-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, ors/speculative/enable speculative/
Quoted 8 lines
Quoted 6 lines
man2/prctl.2 arguments must be specified as 0; otherwise the call fails with the error · line 1224
Quoted 4 lines
man2/prctl.2 +4
-0+.\" 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.
Quoted 7 lines
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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
A message that is not in the archive (sent off-list or not yet received): 604879eb-1c7e-d08b-a6b8-165e4259b60c-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Re: [PATCH 10/14] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls
Quoted 76 lines · Michael Kerrisk (man-pages)
Quoted 38 lines · Dave Martin
Quoted 37 lines · Michael Kerrisk (man-pages)
Hello Dave,
Quoted 6 lines · Dave Martin
Add the
PR_SPEC_INDIRECT_BRANCH"misfeature" added in Linux 4.20 forPR_SET_SPECULATION_CTRLandPR_GET_SPECULATION_CTRL.Signed-off-by Dave Martin <[email protected]>Cc Tim Chen <tim.c.chen-VuQAYsv1563Yd54FQh9/[email protected]>Cc Thomas Gleixner <[email protected]>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.
Quoted 9 lines
--- man2/prctl.2 | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-)man2/prctl.2 +0
-0man2/prctl.2 arguments must be specified as 0; otherwise the call fails with the error · line 1220
Quoted 10 lines
man2/prctl.2 +4
-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, ors/speculative/enable speculative/
Quoted 8 lines
Quoted 6 lines
man2/prctl.2 arguments must be specified as 0; otherwise the call fails with the error · line 1224
Quoted 4 lines
man2/prctl.2 +4
-0+.\" 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.
Quoted 7 lines
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.
Quoted 7 lines
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 12/14 prctl.2: Clarify the unsupported hardware case of EINVAL
In reply to a message not in the archiveprctls 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.
--- man2/prctl.2 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
man2/prctl.2 +2 -1
@@ -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
Signature · 1 line
2.1.4
Re: [PATCH 12/14] prctl.2: Clarify the unsupported hardware case of EINVAL
Hello Dave,
Quoted 5 lines · 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.
Quoted 7 lines
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 <[email protected]>
Thanks. Patch applied
Cheers,
Michael
Quoted 19 lines
--- man2/prctl.2 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)man2/prctl.2 +2
-1@@ -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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH 1/14 prctl.2: tfix clarify that prctl can apply to threads
In reply to Dave MartinThe 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.
--- man2/prctl.2 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)
man2/prctl.2 +5 -1
@@ -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.
Signature · 1 line
2.1.4
A message that is not in the archive (sent off-list or not yet received): 1589301419-24459-2-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
Re: [PATCH 01/14] prctl.2: tfix clarify that prctl can apply to threads
Quoted 8 lines · 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.
Thanks, Dave. Patch applied.
Cheers,
Michael
Quoted 30 lines
Signed-off-by Dave Martin <[email protected]>--- man2/prctl.2 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)man2/prctl.2 +5
-1@@ -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.
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH 3/14 prctl.2: tfix mis-description of thread ID values in procfs
In reply to Dave MartinUnder 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.
--- man2/prctl.2 | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)
man2/prctl.2 +4 -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,
Signature · 1 line
2.1.4
Re: [PATCH 03/14] prctl.2: tfix mis-description of thread ID values in procfs
Quoted 5 lines · 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.
Thanks, Dave. Patch applied.
Cheers,
Michael
Quoted 23 lines
Signed-off-by Dave Martin <[email protected]>--- man2/prctl.2 | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)man2/prctl.2 +4
-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,
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH 4/14 prctl.2: srcfix add comments for navigation
In reply to Dave MartinThe 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.
--- man2/prctl.2 | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+)
man2/prctl.2 +48 -0
@@ -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.
Signature · 1 line
2.1.4
Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation
Hi Dave,
Quoted 4 lines · 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.
Quoted 8 lines
For each actual prctl, add a comment of the form
.\" prctl
PR_FOOto 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
Quoted 374 lines
Signed-off-by Dave Martin <[email protected]>--- man2/prctl.2 | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+)man2/prctl.2 +48
-0@@ -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.
Signature · 3 lines
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
Quoted 16 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 4 lines · 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.
Quoted 8 lines
For each actual prctl, add a comment of the form
.\" prctl
PR_FOOto 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.
Quoted 6 lines
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.
Quoted 10 lines
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
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation
Hi Dave,
Quoted 35 lines · Dave Martin
Quoted 16 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 4 lines · 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.
Quoted 8 lines
For each actual prctl, add a comment of the form
.\" prctl
PR_FOOto 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.
Quoted 6 lines
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.
Quoted 9 lines
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
.\" ==========================
Quoted 8 lines
Quoted 1 line
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.
Quoted 4 lines
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
Signature · 3 lines
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
Quoted 47 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 35 lines · Dave Martin
Quoted 16 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 4 lines · 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.
Quoted 8 lines
For each actual prctl, add a comment of the form
.\" prctl
PR_FOOto 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.
Quoted 6 lines
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.
Quoted 9 lines
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
.\" ==========================
Quoted 8 lines
Quoted 1 line
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===
Quoted 8 lines
Okay -- I'll give that some thought.
Quoted 4 lines
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
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation
Hi Dave,
Quoted 53 lines · Dave Martin
Quoted 52 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 35 lines · Dave Martin
Quoted 16 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 4 lines · 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.
Quoted 8 lines
For each actual prctl, add a comment of the form
.\" prctl
PR_FOOto 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.
Quoted 6 lines
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.
Quoted 9 lines
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
.\" ==========================
Quoted 8 lines
Quoted 1 line
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.
Quoted 3 lines
If you prefer to reject this patch, I'm happy to rebase and repost the series as appropriate.
Quoted 6 lines
Quoted 3 lines
Quoted 1 line
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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
A message that is not in the archive (sent off-list or not yet received): 022b1d7f-8381-a9a8-b5aa-907143fd4831-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Re: [PATCH 04/14] prctl.2: srcfix add comments for navigation
Quoted 58 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 55 lines · Dave Martin
Quoted 54 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 35 lines · Dave Martin
Quoted 16 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 4 lines · 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.
Quoted 8 lines
For each actual prctl, add a comment of the form
.\" prctl
PR_FOOto 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.
Quoted 6 lines
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.
Quoted 9 lines
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
.\" ==========================
Quoted 8 lines
Quoted 1 line
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.
Quoted 4 lines
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.
Quoted 7 lines
Quoted 4 lines
Quoted 1 line
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 8/14 prctl.2: Work around bogus constant "maxsig" in PR_SET_PDEATHSIG
In reply to Dave MartinThe 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.)
--- man2/prctl.2 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
man2/prctl.2 +3 -1
@@ -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
Signature · 1 line
2.1.4
A message that is not in the archive (sent off-list or not yet received): 1589301419-24459-9-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
Re: [PATCH 08/14] prctl.2: Work around bogus constant "maxsig" in PR_SET_PDEATHSIG
Quoted 8 lines · Dave Martin
The description of
PR_SET_PDEATHSIGrefers 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
Quoted 21 lines
Signed-off-by Dave Martin <[email protected]>--- man2/prctl.2 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)man2/prctl.2 +3
-1@@ -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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
PATCH 11/14 prctl.2: Add PR_SPEC_DISABLE_NOEXEC for SPECULATION_CTRL prctls
In reply to Dave MartinAdd 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.
--- man2/prctl.2 | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-)
man2/prctl.2 +20 -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 ()
Signature · 1 line
2.1.4
PATCH 13/14 prctl.2: Add SVE prctls (arm64)
In reply to Dave MartinAdd documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL prctls added in Linux 4.15 for arm64.
---
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(+)
man2/prctl.2 +112 -0
@@ -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
Signature · 1 line
2.1.4
A message that is not in the archive (sent off-list or not yet received): 1589301419-24459-14-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)
Hi Dave,
Quoted 9 lines · Dave Martin
man2/prctl.2 +1
-0@@ -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
man2/prctl.2 call failing with the error · line 1304
Quoted 10 lines
man2/prctl.2 +10
-0+.\" 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 :(
man2/prctl.2 call failing with the error · line 1309
Quoted 5 lines
man2/prctl.2 +5
-0+.IP +The bits of +.I arg2 +corresponding to +.B SVE_VL_LEN_MASK
PR_SVE_LEN_MASK
Quoted 4 lines
man2/prctl.2 +4
-0+must be set to the desired vector length in bytes. +In addition, +.I arg2 +may include zero or more of the following flags:
man2/prctl.2 call failing with the error · line 1323
Quoted 10 lines
man2/prctl.2 +10
-0+.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)
man2/prctl.2 call failing with the error · line 1330
Quoted 7 lines
man2/prctl.2 +7
-0+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()?
man2/prctl.2 call failing with the error · line 1336
Quoted 6 lines
man2/prctl.2 +6
-0+.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 ;)
man2/prctl.2 call failing with the error · line 1343
Quoted 7 lines
man2/prctl.2 +7
-0+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?
man2/prctl.2 call failing with the error · line 1347
Quoted 4 lines
man2/prctl.2 +4
-0+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?
man2/prctl.2 call failing with the error · line 1349
Quoted 2 lines
man2/prctl.2 +2
-0+.IP +If neither of the above flags is included in
are included
Quoted 14 lines
man2/prctl.2 +14
-0+.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)
man2/prctl.2 call failing with the error · line 1373
Quoted 10 lines
man2/prctl.2 +10
-0+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?
man2/prctl.2 call failing with the error · line 1377
Quoted 4 lines
man2/prctl.2 +4
-0+.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).
man2/prctl.2 call failing with the error · line 1387
Quoted 10 lines
man2/prctl.2 +10
-0+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
Quoted 22 lines
man2/prctl.2 +8
-0+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
man2/prctl.2 and unused arguments to · line 1931
Quoted 10 lines
man2/prctl.2 +10
-0+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)
Quoted 17 lines · Will Deacon
Hi Dave,
Quoted 14 lines · Dave Martin
man2/prctl.2 +6
-0@@ -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,
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1304
Quoted 5 lines
man2/prctl.2 +5
-0+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.
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1309
Quoted 6 lines
man2/prctl.2 +5
-0+.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.
Quoted 8 lines
Quoted 8 lines
man2/prctl.2 +8
-0+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
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1323
Quoted 6 lines
man2/prctl.2 +6
-0+.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.
Quoted 4 lines
Quoted 4 lines
man2/prctl.2 +4
-0+If +.B PR_SVE_VL_INHERIT +is also included in +.IR arg2 ,
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1330
Quoted 3 lines
man2/prctl.2 +3
-0+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 bothPR_SVE_SET_VL_ONEXECandPR_SVE_VL_INHERITare specified, is the vector length preserved or reset on the nextexecve()?
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.
Quoted 9 lines
man2/prctl.2 call failing with the error · line 1336
Quoted 6 lines
man2/prctl.2 +6
-0+.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.
Quoted 11 lines
man2/prctl.2 call failing with the error · line 1343
Quoted 8 lines
man2/prctl.2 +7
-0+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?
Quoted 6 lines
man2/prctl.2 call failing with the error · line 1347
Quoted 4 lines
man2/prctl.2 +4
-0+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.
Quoted 5 lines
man2/prctl.2 call failing with the error · line 1349
Quoted 3 lines
man2/prctl.2 +2
-0+.IP +If neither of the above flags is included inare 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.
Quoted 18 lines
Quoted 18 lines
man2/prctl.2 +18
-0+.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).
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1373
Quoted 6 lines
man2/prctl.2 +6
-0+.\" 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_VLthough, 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.
Quoted 7 lines
man2/prctl.2 call failing with the error · line 1377
Quoted 4 lines
man2/prctl.2 +4
-0+.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.
Quoted 4 lines
Quoted 4 lines
man2/prctl.2 +4
-0+The bits corresponding to +.B PR_SVE_VL_LEN_MASK +contain the currently configured vector length in bytes. +The bit corresponding to
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1387
Quoted 6 lines
man2/prctl.2 +6
-0+.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 isto determine
Ack
Quoted 26 lines
Quoted 26 lines
man2/prctl.2 +12
-0+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
Quoted 8 lines
man2/prctl.2 and unused arguments to · line 1931
Quoted 6 lines
man2/prctl.2 +6
-0+contains invalid flags, or +.I arg2 +& +.B SVE_VL_LEN_MASK +is not a valid vector length. +.TP
PR_SVE_GET_VLcan return-EINVALif 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)
Hi,
Quoted 18 lines · Dave Martin
Quoted 17 lines · Will Deacon
Hi Dave,
Quoted 14 lines · Dave Martin
man2/prctl.2 +6
-0@@ -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,
Quoted 8 lines
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1304
Quoted 5 lines
man2/prctl.2 +5
-0+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...
Quoted 2 lines
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.
Quoted 10 lines
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.
Quoted 63 lines
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_VLwill 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.
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1309
Quoted 6 lines
man2/prctl.2 +5
-0+.IP +The bits of +.I arg2 +corresponding to +.B SVE_VL_LEN_MASK
PR_SVE_LEN_MASKHmm, not sure how that happened. Good spot!
I'll recheck that all the names are real when reposting.
Quoted 8 lines
Quoted 8 lines
man2/prctl.2 +8
-0+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 acrossQuoted 8 lines
man2/prctl.2 call failing with the error · line 1323
Quoted 6 lines
man2/prctl.2 +6
-0+.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_SVEformat 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.
Quoted 4 lines
Quoted 4 lines
man2/prctl.2 +4
-0+If +.B PR_SVE_VL_INHERIT +is also included in +.IR arg2 ,Quoted 8 lines
man2/prctl.2 call failing with the error · line 1330
Quoted 3 lines
man2/prctl.2 +3
-0+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 bothPR_SVE_SET_VL_ONEXECandPR_SVE_VL_INHERITare specified, is the vector length preserved or reset on the nextexecve()?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 subsequentexecs().
Quoted 7 lines
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.)
Quoted 10 lines
Quoted 9 lines
man2/prctl.2 call failing with the error · line 1336
Quoted 6 lines
man2/prctl.2 +6
-0+.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 ;)
Quoted 4 lines
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.
Quoted 24 lines
Quoted 11 lines
man2/prctl.2 call failing with the error · line 1343
Quoted 8 lines
man2/prctl.2 +7
-0+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?
Quoted 6 lines
man2/prctl.2 call failing with the error · line 1347
Quoted 4 lines
man2/prctl.2 +4
-0+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.
Quoted 4 lines
Quoted 3 lines
man2/prctl.2 +2
-0+.IP +If neither of the above flags is included in
Quoted 7 lines
Quoted 1 line
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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
A message that is not in the archive (sent off-list or not yet received): a01fc572-cac8-1932-c3e5-c70184417ca3-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)
Quoted 45 lines · Michael Kerrisk (man-pages)
Hi,
Quoted 18 lines · Dave Martin
Quoted 17 lines · Will Deacon
Hi Dave,
Quoted 14 lines · Dave Martin
man2/prctl.2 +6
-0@@ -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,Quoted 8 lines
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1304
Quoted 5 lines
man2/prctl.2 +5
-0+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...
Quoted 2 lines
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.
Quoted 4 lines
glibc explicitly has
extern int prctl (int __option, ...);
Quoted 8 lines
Quoted 6 lines
(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.)
Quoted 121 lines
Quoted 64 lines
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_VLwill 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.
Quoted 8 lines
man2/prctl.2 call failing with the error · line 1309
Quoted 6 lines
man2/prctl.2 +5
-0+.IP +The bits of +.I arg2 +corresponding to +.B SVE_VL_LEN_MASK
PR_SVE_LEN_MASKHmm, not sure how that happened. Good spot!
I'll recheck that all the names are real when reposting.
Quoted 8 lines
Quoted 8 lines
man2/prctl.2 +8
-0+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 acrossQuoted 8 lines
man2/prctl.2 call failing with the error · line 1323
Quoted 6 lines
man2/prctl.2 +6
-0+.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_SVEformat 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.
Quoted 4 lines
Quoted 4 lines
man2/prctl.2 +4
-0+If +.B PR_SVE_VL_INHERIT +is also included in +.IR arg2 ,Quoted 8 lines
man2/prctl.2 call failing with the error · line 1330
Quoted 3 lines
man2/prctl.2 +3
-0+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 bothPR_SVE_SET_VL_ONEXECandPR_SVE_VL_INHERITare specified, is the vector length preserved or reset on the nextexecve()?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 subsequentexecs().Quoted 7 lines
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.)
Quoted 10 lines
Quoted 9 lines
man2/prctl.2 call failing with the error · line 1336
Quoted 6 lines
man2/prctl.2 +6
-0+.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 ;)
Quoted 4 lines
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.Quoted 26 lines
Quoted 11 lines
man2/prctl.2 call failing with the error · line 1343
Quoted 8 lines
man2/prctl.2 +7
-0+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?
Quoted 6 lines
man2/prctl.2 call failing with the error · line 1347
Quoted 4 lines
man2/prctl.2 +4
-0+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.
Quoted 5 lines
man2/prctl.2 call failing with the error · line 1349
Quoted 3 lines
man2/prctl.2 +2
-0+.IP +If neither of the above flags is included inare included
Quoted 8 lines
Quoted 5 lines
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!
Quoted 2 lines
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
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 13/14] prctl.2: Add SVE prctls (arm64)
Quoted 15 lines · Dave Martin
Quoted 14 lines · Michael Kerrisk (man-pages)
Quoted 12 lines · Dave Martin
Quoted 1 line · Will Deacon
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.
Quoted 4 lines
Quoted 1 line
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.
Quoted 2 lines
I'll propose to get that written down in the kernel source somewhere if so.
That would be a really good idea, actually!
Quoted 5 lines
(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.
Quoted 9 lines
Quoted 9 lines
Quoted 9 lines
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_VLwill 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.
Quoted 13 lines
Quoted 13 lines
Quoted 13 lines
Quoted 12 lines
Review
Quoted 7 lines
(quoted diff) +7
-0+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 bothPR_SVE_SET_VL_ONEXECandPR_SVE_VL_INHERITare specified, is the vector length preserved or reset on the nextexecve()?
Quoted 8 lines
Quoted 8 lines
Quoted 8 lines
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 subsequentexecs().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)
Quoted 18 lines · Will Deacon
Quoted 17 lines · Dave Martin
Quoted 15 lines · Michael Kerrisk (man-pages)
Quoted 4 lines · Dave Martin
Quoted 1 line · Will Deacon
On Tue, May 12, 2020 at 05:36:58PM +0100, Dave Martin wrote:
glibc explicitly has
Quoted 8 lines
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.
Quoted 7 lines
Quoted 2 lines
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.
Quoted 11 lines
Quoted 2 lines
I'll propose to get that written down in the kernel source somewhere if so.
That would be a really good idea, actually!
Quoted 5 lines
(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.)
Quoted 3 lines
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.
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
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_VLwill ever want an argument.
Quoted 7 lines
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
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
Quoted 22 lines
Quoted 13 lines
Quoted 13 lines
Quoted 13 lines
Quoted 12 lines
Review
Quoted 7 lines
(quoted diff) +7
-0+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 bothPR_SVE_SET_VL_ONEXECandPR_SVE_VL_INHERITare specified, is the vector length preserved or reset on the nextexecve()?Quoted 8 lines
Quoted 8 lines
Quoted 8 lines
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 subsequentexecs().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?
Quoted 8 lines
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 bothPR_SVE_SET_VL_ONEXECandPR_SVE_VL_INHERITwithout 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)
In reply to Will DeaconQuoted 5 lines · Will Deacon
Quoted 4 lines · Dave Martin
Quoted 3 lines · Michael Kerrisk (man-pages)
Quoted 2 lines · Dave Martin
Quoted 1 line · Will Deacon
On Tue, May 12, 2020 at 05:36:58PM +0100, Dave Martin wrote:
[...]
Quoted 22 lines
Quoted 13 lines
Quoted 13 lines
Quoted 13 lines
Quoted 12 lines
Review
Quoted 7 lines
(quoted diff) +7
-0+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 bothPR_SVE_SET_VL_ONEXECandPR_SVE_VL_INHERITare specified, is the vector length preserved or reset on the nextexecve()?Quoted 8 lines
Quoted 8 lines
Quoted 8 lines
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 subsequentexecs().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?
Quoted 6 lines
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 bothPR_SVE_SET_VL_ONEXECandPR_SVE_VL_INHERITwithout 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)
In reply to Dave MartinAdd documentation for the PR_PAC_RESET_KEYS ioctl added in Linux 5.0 for arm64.
---
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(+)
man2/prctl.2 +61 -0
@@ -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
Signature · 1 line
2.1.4
Re: [PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)
Hi Dave,
Quoted 34 lines · Dave Martin
man2/prctl.2 +26
-0@@ -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.
man2/prctl.2 behavior. · line 988
Quoted 10 lines
man2/prctl.2 +10
-0+.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().
Quoted 18 lines
man2/prctl.2 +11
-0+.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 ,
man2/prctl.2 are not 0. · line 1979
Quoted 10 lines
man2/prctl.2 +10
-0+.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)
Quoted 43 lines · Will Deacon
Hi Dave,
Quoted 40 lines · Dave Martin
man2/prctl.2 +32
-0@@ -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
Quoted 8 lines
man2/prctl.2 behavior. · line 988
Quoted 4 lines
man2/prctl.2 +4
-0+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 theprctl()unnecessarily immediately following anexec().
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.
Quoted 24 lines
Quoted 24 lines
man2/prctl.2 +16
-0+.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
Quoted 8 lines
man2/prctl.2 are not 0. · line 1979
Quoted 5 lines
man2/prctl.2 +5
-0+.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
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)
Quoted 23 lines · Dave Martin
Quoted 11 lines · Will Deacon
man2/prctl.2 behavior. · line 988
Quoted 6 lines · Dave Martin
man2/prctl.2 +6
-0+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 theprctl()unnecessarily immediately following anexec().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 thisprctl()call.PR_PAC_RESET_KEYSis intended for custom situations that do not involveexecve(), such as creating a new managed run-time sandbox."
Quoted 3 lines
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.
Quoted 25 lines
Quoted 16 lines
Quoted 16 lines
man2/prctl.2 +12
-0@@ -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 ; +orQuoted 8 lines
man2/prctl.2 are not 0. · line 1979
Quoted 5 lines
man2/prctl.2 +5
-0+.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?
Quoted 3 lines
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)
Quoted 56 lines · Will Deacon
Quoted 23 lines · Dave Martin
Quoted 11 lines · Will Deacon
man2/prctl.2 behavior. · line 988
Quoted 6 lines · Dave Martin
man2/prctl.2 +6
-0+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 theprctl()unnecessarily immediately following anexec().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 thisprctl()call.PR_PAC_RESET_KEYSis intended for custom situations that do not involveexecve(), such as creating a new managed run-time sandbox."Quoted 3 lines
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.
Quoted 25 lines
Quoted 24 lines
Quoted 11 lines
man2/prctl.2 +7
-0@@ -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 ,man2/prctl.2 are not 0. · line 1979
Quoted 10 lines
man2/prctl.2 +10
-0+.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?
Quoted 7 lines
Quoted 3 lines
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
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)
Quoted 4 lines · Dave Martin
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
Michael Kerrisk (man-pages)
AppliedHi Dave,
Quoted 18 lines · 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.
Quoted 8 lines
* 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_CTRLrequires a bit more discussion and will be posted separately.)
Thanks. This is great!
Quoted 9 lines
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.
Quoted 1 line
Again, I'm happy to do that if needed.
(No need.)
Except as noted below, patches have been applied:
Quoted 11 lines
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" inPR_SET_PDEATHSIGprctl.2: tfix minor punctuation inSPECULATION_CTRLprctls prctl.2: AddPR_SPEC_INDIRECT_BRANCHforSPECULATION_CTRLprctls
Applied, but not yet pushed.
Quoted 1 line
prctl.2: Add
PR_SPEC_DISABLE_NOEXECforSPECULATION_CTRLprctls
Applied, but not yet pushed.
Quoted 2 lines
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.
Quoted 1 line
prctl.2: Add
PR_PAC_RESET_KEYS(arm64)
Will had comments. I'm presuming there will be a v2 of this patch.
Cheers,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/