prctl.2 man page updates for Linux 5.6
Subsystems (2)
v3 cover prctl.2 man page updates for Linux 5.6
A bunch of updates to the prctl(2) man page to fill in missing prctls (mostly) up to Linux 5.6 (along with a few other tweaks and fixes).
Patches from the v2 series [1] that have been applied or rejected already have been dropped.
All that remain here now are the SVE and tagged address ABI controls for arm64.
Dave Martin (2):
prctl.2: Add SVE prctls (arm64)
prctl.2: Add tagged address ABI control prctls (arm64)
man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 331 insertions(+)
Signature · 1 line
2.1.4
A message that is not in the archive (sent off-list or not yet received): 1593020162-9365-1-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
PATCH v3 1/2 prctl.2: Add SVE prctls (arm64)
Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL prctls added in Linux 4.15 for arm64.
---
Since v2:
* Clarify that the arg2 enumeration for PR_SVE_SET_VL applies to the bith _other than_ the PR_SVE_VL_LEN_MASK bits, rather than to all the bits.
* Clarify return value semantics for PR_SVE_SET_VL, to highlight that there is no PR_SVE_SET_VL_ONEXEC in the return value and refer to PR_SVE_GET_VL for the rest of the definition. Also clarify when the vector length given in the return value actually takes effect.
* Reorder some documentation cross-references to avoid ambiguity about what they apply to.
--- man2/prctl.2 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+)
man2/prctl.2 +170 -0
@@ -1370,6 +1370,158 @@ 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 "(int) arg2" . +Arguments +.IR arg3 ", " arg4 " and " arg5 +are ignored. +.IP +The bits of +.I arg2 +corresponding to +.B 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 particular, specifying +.B SVE_VL_MAX +(defined in +.I <asm/sigcontext.h>) +for the +.B PR_SVE_VL_LEN_MASK +bits requests the maximum supported vector length. +.IP +In addition, the other bits of +.I arg2 +must be set to one of the following combinations of flags: +.RS +.TP +.B 0 +Perform the change immediately. +At the next +.BR execve (2) +in the thread, +the vector length will be reset to the value configured in +.IR /proc/sys/abi/sve_default_vector_length . +.TP +.B PR_SVE_VL_INHERIT +Perform the change immediately. +Subsequent +.BR execve (2) +calls will preserve the new vector length. +.TP +.B PR_SVE_SET_VL_ONEXEC +Defer the change, so that it is performed at the next +.BR execve (2) +in the thread. +Further +.BR execve (2) +calls will reset the vector length to the value configured in +.IR /proc/sys/abi/sve_default_vector_length . +.TP +.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT" +Defer the change, so that it is performed at the next +.BR execve (2) +in the thread. +Further +.BR execve (2) +calls will preserve the new vector length. +.RE +.IP +In all cases, +any previously pending deferred change is canceled. +.IP +The call fails with error +.B EINVAL +if SVE is not supported on the platform, if +.I arg2 +is unrecognized or invalid, or the value in the bits of +.I arg2 +corresponding to +.B PR_SVE_VL_LEN_MASK +is outside the range +.BR SVE_VL_MIN .. SVE_VL_MAX +or is not a multiple of 16. +.IP +On success, +a nonnegative value is returned that describes the +.I selected +configuration. +If +.B PR_SVE_SET_VL_ONEXEC +was included in +.IR arg2 , +then the configuration described by the return value +will take effect at the next +.BR execve (). +Otherwise, the configuration is already in effect when the +.B PR_SVE_SET_VL +call returns. +In either case, the value is encoded in the same way as the return value of +.BR PR_SVE_GET_VL . +Note that there is no explicit flag in the return value +corresponding to +.BR PR_SVE_SET_VL_ONEXEC . +.IP +The configuration (including any pending deferred change) +is inherited across +.BR fork (2) +and +.BR clone (2). +.IP +For more information, see the kernel source file +.I Documentation/arm64/sve.rst +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed +(or +.I Documentation/arm64/sve.txt +before Linux 5.3). +.IP +.B Warning: +Because the compiler or run-time environment +may be using SVE, using this call without the +.B PR_SVE_SET_VL_ONEXEC +flag may crash 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. +.\" 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. +.IP +Arguments +.IR arg2 ", " arg3 ", " arg4 " and " arg5 +are ignored. +.IP +Providing that the kernel and platform support SVE +this operation always succeeds, +returning a nonnegative value that 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 to determine whether there is +a pending vector length change that has not yet taken effect. +.IP +For more information, see the kernel source file +.I Documentation/arm64/sve.rst +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed +(or +.I Documentation/arm64/sve.txt +before Linux 5.3). .\" .\" prctl PR_TASK_PERF_EVENTS_DISABLE .TP
@@ -1613,6 +1765,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 ,
@@ -1904,6 +2058,22 @@ See the description of .B PR_PAC_RESET_KEYS above for details. .TP +.B EINVAL +.I option +is +.B PR_SVE_SET_VL +and the arguments are invalid or unsupported, +or SVE is not available on this platform. +See the description of +.B PR_SVE_SET_VL +above for details. +.TP +.B EINVAL +.I option +is +.B PR_SVE_GET_VL +and SVE is not available on this platform. +.TP .B ENODEV .I option was
Signature · 1 line
2.1.4
Re: [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64)
Hi Dave,
Quoted 15 lines · Dave Martin
Add documentation for the the
PR_SVE_SET_VLandPR_SVE_GET_VLprctls added in Linux 4.15 for arm64.Signed-off-by Dave Martin <[email protected]>Cc Catalin Marinas <[email protected]>Cc Will Deacon <[email protected]>---
Since v2:
* Clarify that the arg2 enumeration for
PR_SVE_SET_VLapplies to the bith_otherthan_thePR_SVE_VL_LEN_MASKbits, rather than to all the bits.
Quoted 7 lines
* Clarify return value semantics for
PR_SVE_SET_VL, to highlight that there is noPR_SVE_SET_VL_ONEXECin the return value and refer toPR_SVE_GET_VLfor the rest of the definition. Also clarify when the vector length given in the return value actually takes effect.* Reorder some documentation cross-references to avoid ambiguity about what they apply to.
Nicely written patch! I've applied locally, but won't push just yet, to allow for some reviews/acks to come in.
Thanks,
Michael
Quoted 200 lines
--- man2/prctl.2 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+)man2/prctl.2 +170
-0@@ -1370,6 +1370,158 @@ 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 "(int) arg2" . +Arguments +.IR arg3 ", " arg4 " and " arg5 +are ignored. +.IP +The bits of +.I arg2 +corresponding to +.B 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 particular, specifying +.B SVE_VL_MAX +(defined in +.I <asm/sigcontext.h>) +for the +.B PR_SVE_VL_LEN_MASK +bits requests the maximum supported vector length. +.IP +In addition, the other bits of +.I arg2 +must be set to one of the following combinations of flags: +.RS +.TP +.B 0 +Perform the change immediately. +At the next +.BR execve (2) +in the thread, +the vector length will be reset to the value configured in +.IR /proc/sys/abi/sve_default_vector_length . +.TP +.B PR_SVE_VL_INHERIT +Perform the change immediately. +Subsequent +.BR execve (2) +calls will preserve the new vector length. +.TP +.B PR_SVE_SET_VL_ONEXEC +Defer the change, so that it is performed at the next +.BR execve (2) +in the thread. +Further +.BR execve (2) +calls will reset the vector length to the value configured in +.IR /proc/sys/abi/sve_default_vector_length . +.TP +.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT" +Defer the change, so that it is performed at the next +.BR execve (2) +in the thread. +Further +.BR execve (2) +calls will preserve the new vector length. +.RE +.IP +In all cases, +any previously pending deferred change is canceled. +.IP +The call fails with error +.B EINVAL +if SVE is not supported on the platform, if +.I arg2 +is unrecognized or invalid, or the value in the bits of +.I arg2 +corresponding to +.B PR_SVE_VL_LEN_MASK +is outside the range +.BR SVE_VL_MIN .. SVE_VL_MAX +or is not a multiple of 16. +.IP +On success, +a nonnegative value is returned that describes the +.I selected +configuration. +If +.B PR_SVE_SET_VL_ONEXEC +was included in +.IR arg2 , +then the configuration described by the return value +will take effect at the next +.BR execve (). +Otherwise, the configuration is already in effect when the +.B PR_SVE_SET_VL +call returns. +In either case, the value is encoded in the same way as the return value of +.BR PR_SVE_GET_VL . +Note that there is no explicit flag in the return value +corresponding to +.BR PR_SVE_SET_VL_ONEXEC . +.IP +The configuration (including any pending deferred change) +is inherited across +.BR fork (2) +and +.BR clone (2). +.IP +For more information, see the kernel source file +.I Documentation/arm64/sve.rst +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed +(or +.I Documentation/arm64/sve.txt +before Linux 5.3). +.IP +.B Warning: +Because the compiler or run-time environment +may be using SVE, using this call without the +.B PR_SVE_SET_VL_ONEXEC +flag may crash 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. +.\" 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. +.IP +Arguments +.IR arg2 ", " arg3 ", " arg4 " and " arg5 +are ignored. +.IP +Providing that the kernel and platform support SVE +this operation always succeeds, +returning a nonnegative value that 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 to determine whether there is +a pending vector length change that has not yet taken effect. +.IP +For more information, see the kernel source file +.I Documentation/arm64/sve.rst +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed +(or +.I Documentation/arm64/sve.txt +before Linux 5.3). .\" .\" prctl PR_TASK_PERF_EVENTS_DISABLE .TP@@ -1613,6 +1765,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 ,@@ -1904,6 +2058,22 @@ See the description of .B PR_PAC_RESET_KEYS above for details. .TP +.B EINVAL +.I option +is +.B PR_SVE_SET_VL +and the arguments are invalid or unsupported, +or SVE is not available on this platform. +See the description of +.B PR_SVE_SET_VL +above for details. +.TP +.B EINVAL +.I option +is +.B PR_SVE_GET_VL +and SVE is not available on this platform. +.TP .B ENODEV .I option was
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 v3 2/2 prctl.2: Add tagged address ABI control prctls (arm64)
In reply to a message not in the archiveAdd documentation for the the PR_SET_TAGGED_ADDR_CTRL and PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.
---
Kept Catalin's Reviewed-by, since the changes are pretty minor.
Changes since v2:
* Clarified type of PR_SET_TAGGED_ADDR_CTRL arg2.
* Added Linux commit where enforecement of zeroing reserved args was added for PR_SET_TAGGED_ADDR_CTRL.
* Added explicit text regarding how to disable the tagged-address ABI globally through sysctl.
* Rearrange the tagged argument syscall exclusion list so that shmdt() isn't called out specially. The reader probably doesn't care about this history here.
* Minor rewordings.
--- man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+)
man2/prctl.2 +161 -0
@@ -1522,6 +1522,148 @@ For more information, see the kernel source file (or .I Documentation/arm64/sve.txt before Linux 5.3). +.\" prctl PR_SET_TAGGED_ADDR_CTRL +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d +.TP +.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)" +Controls support for passing tagged userspace addresses to the kernel +(i.e., addresses where bits 56\(em63 are not all zero). +.IP +The level of support is selected by +.IR "arg2" , +which can be one of the following: +.RS +.TP +.B 0 +Addresses that are passed +for the purpose of being dereferenced by the kernel +must be untagged. +.TP +.B PR_TAGGED_ADDR_ENABLE +Addresses that are passed +for the purpose of being dereferenced by the kernel +may be tagged, with the exceptions summarized below. +.RE +.IP +The remaining arguments +.IR arg3 ", " arg4 " and " arg5 +must all be zero. +.\" Enforcement added in +.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95 +.IP +On success, the mode specified in +.I arg2 +is set for the calling thread and the the return value is 0. +If the arguments are invalid, +the mode specified in +.I arg2 +is unrecognized, +or if this feature is unsupported by the kernel +or disabled via +.IR /proc/sys/abi/tagged_addr_disabled , +the call fails with +.BR EINVAL . +.IP +In particular, if +.BR prctl ( PR_SET_TAGGED_ADDR_CTRL , +0, 0, 0, 0) +fails with +.B EINVAL +then all addresses passed to the kernel must be untagged. +.IP +Irrespective of which mode is set, +addresses passed to certain interfaces +must always be untagged: +.RS +.IP \(em +.BR brk (2), +.BR mmap (2), +.BR shmat (2), +.BR shmdt (2), +and the +.I new_address +argument of +.BR mremap (2). +.IP +(Prior to Linux 5.6 these accepted tagged addresses, +but the behaviour may not be what you expect. +Don't rely on it.) +.IP \(em +\(oqpolymorphic\(cq interfaces +that accept pointers to arbitrary types cast to a +.I void * +or other generic type, specifically +.BR prctl (2), +.BR ioctl (2), +and in general +.BR setsockopt (2) +(only certain specific +.BR setsockopt (2) +options allow tagged addresses). +.RE +.IP +This list of exclusions may shrink +when moving from one kernel version to a later kernel version. +While the kernel may make some guarantees +for backwards compatibility reasons, +for the purposes of new software +the effect of passing tagged addresses to these interfaces +is unspecified. +.IP +The mode set by this call is inherited across +.BR fork (2) +and +.BR clone (2). +The mode is reset by +.BR execve (2) +to 0 +(i.e., tagged addresses not permitted in the user/kernel ABI). +.IP +For more information, see the kernel source file +.IR Documentation/arm64/tagged\-address\-abi.rst . +.IP +.B Warning: +This call is primarily intended for use by the run-time environment. +A successful +.B PR_SET_TAGGED_ADDR_CTRL +call elsewhere may crash the calling process. +The conditions for using it safely are complex and system-dependent; +Don't use it unless you know what you are doing. +.\" prctl PR_GET_TAGGED_ADDR_CTRL +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d +.TP +.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)" +Returns the current tagged address mode +for the calling thread. +.IP +Arguments +.IR arg2 ", " arg3 ", " arg4 " and " arg5 +must all be zero. +.IP +If the arguments are invalid +or this feature is disabled or unsupported by the kernel, +the call fails with +.BR EINVAL . +In particular, if +.BR prctl ( PR_GET_TAGGED_ADDR_CTRL , +0, 0, 0, 0) +fails with +.BR EINVAL , +then this feature is definitely either unsupported, +or disabled via +.IR /proc/sys/abi/tagged_addr_disabled . +In this case, +all addresses passed to the kernel must be untagged. +.IP +Otherwise, the call returns a nonnegative value +describing the current tagged address mode, +encoded in the same way as the +.I arg2 +argument of +.BR PR_SET_TAGGED_ADDR_CTRL . +.IP +For more information, see the kernel source file +.IR Documentation/arm64/tagged\-address\-abi.rst . .\" .\" prctl PR_TASK_PERF_EVENTS_DISABLE .TP
@@ -1767,6 +1909,7 @@ On success, .BR PR_GET_SPECULATION_CTRL , .BR PR_SVE_GET_VL , .BR PR_SVE_SET_VL , +.BR PR_GET_TAGGED_ADDR_CTRL , .BR PR_GET_THP_DISABLE , .BR PR_GET_TIMING , .BR PR_GET_TIMERSLACK ,
@@ -2074,6 +2217,24 @@ is .B PR_SVE_GET_VL and SVE is not available on this platform. .TP +.B EINVAL +.I option +is +.BR PR_SET_TAGGED_ADDR_CTRL +and the arguments are invalid or unsupported. +See the description of +.B PR_SET_TAGGED_ADDR_CTRL +above for details. +.TP +.B EINVAL +.I option +is +.BR PR_GET_TAGGED_ADDR_CTRL +and the arguments are invalid or unsupported. +See the description of +.B PR_GET_TAGGED_ADDR_CTRL +above for details. +.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): 1593020162-9365-3-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org
Re: [PATCH v3 2/2] prctl.2: Add tagged address ABI control prctls (arm64)
Hi Dave,
Quoted 6 lines · Dave Martin
Add documentation for the the
PR_SET_TAGGED_ADDR_CTRLandPR_GET_TAGGED_ADDR_CTRLprctls added in Linux 5.4 for arm64.Signed-off-by Dave Martin <[email protected]>Reviewed-by Catalin Marinas <[email protected]>Cc Vincenzo Frascino <[email protected]>
Thanks for another nicely written patch! I've applied locally, but won't push just yet, to allow for some (more) reviews/acks to come in.
Thanks,
Michael
Quoted 210 lines
---
Kept Catalin's Reviewed-by, since the changes are pretty minor.
Changes since v2:
* Clarified type of
PR_SET_TAGGED_ADDR_CTRLarg2.* Added Linux commit where enforecement of zeroing reserved args was added for
PR_SET_TAGGED_ADDR_CTRL.* Added explicit text regarding how to disable the tagged-address ABI globally through sysctl.
* Rearrange the tagged argument syscall exclusion list so that
shmdt()isn't called out specially. The reader probably doesn't care about this history here.* Minor rewordings.
--- man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+)man2/prctl.2 +161
-0@@ -1522,6 +1522,148 @@ For more information, see the kernel source file (or .I Documentation/arm64/sve.txt before Linux 5.3). +.\" prctl PR_SET_TAGGED_ADDR_CTRL +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d +.TP +.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)" +Controls support for passing tagged userspace addresses to the kernel +(i.e., addresses where bits 56\(em63 are not all zero). +.IP +The level of support is selected by +.IR "arg2" , +which can be one of the following: +.RS +.TP +.B 0 +Addresses that are passed +for the purpose of being dereferenced by the kernel +must be untagged. +.TP +.B PR_TAGGED_ADDR_ENABLE +Addresses that are passed +for the purpose of being dereferenced by the kernel +may be tagged, with the exceptions summarized below. +.RE +.IP +The remaining arguments +.IR arg3 ", " arg4 " and " arg5 +must all be zero. +.\" Enforcement added in +.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95 +.IP +On success, the mode specified in +.I arg2 +is set for the calling thread and the the return value is 0. +If the arguments are invalid, +the mode specified in +.I arg2 +is unrecognized, +or if this feature is unsupported by the kernel +or disabled via +.IR /proc/sys/abi/tagged_addr_disabled , +the call fails with +.BR EINVAL . +.IP +In particular, if +.BR prctl ( PR_SET_TAGGED_ADDR_CTRL , +0, 0, 0, 0) +fails with +.B EINVAL +then all addresses passed to the kernel must be untagged. +.IP +Irrespective of which mode is set, +addresses passed to certain interfaces +must always be untagged: +.RS +.IP \(em +.BR brk (2), +.BR mmap (2), +.BR shmat (2), +.BR shmdt (2), +and the +.I new_address +argument of +.BR mremap (2). +.IP +(Prior to Linux 5.6 these accepted tagged addresses, +but the behaviour may not be what you expect. +Don't rely on it.) +.IP \(em +\(oqpolymorphic\(cq interfaces +that accept pointers to arbitrary types cast to a +.I void * +or other generic type, specifically +.BR prctl (2), +.BR ioctl (2), +and in general +.BR setsockopt (2) +(only certain specific +.BR setsockopt (2) +options allow tagged addresses). +.RE +.IP +This list of exclusions may shrink +when moving from one kernel version to a later kernel version. +While the kernel may make some guarantees +for backwards compatibility reasons, +for the purposes of new software +the effect of passing tagged addresses to these interfaces +is unspecified. +.IP +The mode set by this call is inherited across +.BR fork (2) +and +.BR clone (2). +The mode is reset by +.BR execve (2) +to 0 +(i.e., tagged addresses not permitted in the user/kernel ABI). +.IP +For more information, see the kernel source file +.IR Documentation/arm64/tagged\-address\-abi.rst . +.IP +.B Warning: +This call is primarily intended for use by the run-time environment. +A successful +.B PR_SET_TAGGED_ADDR_CTRL +call elsewhere may crash the calling process. +The conditions for using it safely are complex and system-dependent; +Don't use it unless you know what you are doing. +.\" prctl PR_GET_TAGGED_ADDR_CTRL +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d +.TP +.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)" +Returns the current tagged address mode +for the calling thread. +.IP +Arguments +.IR arg2 ", " arg3 ", " arg4 " and " arg5 +must all be zero. +.IP +If the arguments are invalid +or this feature is disabled or unsupported by the kernel, +the call fails with +.BR EINVAL . +In particular, if +.BR prctl ( PR_GET_TAGGED_ADDR_CTRL , +0, 0, 0, 0) +fails with +.BR EINVAL , +then this feature is definitely either unsupported, +or disabled via +.IR /proc/sys/abi/tagged_addr_disabled . +In this case, +all addresses passed to the kernel must be untagged. +.IP +Otherwise, the call returns a nonnegative value +describing the current tagged address mode, +encoded in the same way as the +.I arg2 +argument of +.BR PR_SET_TAGGED_ADDR_CTRL . +.IP +For more information, see the kernel source file +.IR Documentation/arm64/tagged\-address\-abi.rst . .\" .\" prctl PR_TASK_PERF_EVENTS_DISABLE .TP@@ -1767,6 +1909,7 @@ On success, .BR PR_GET_SPECULATION_CTRL , .BR PR_SVE_GET_VL , .BR PR_SVE_SET_VL , +.BR PR_GET_TAGGED_ADDR_CTRL , .BR PR_GET_THP_DISABLE , .BR PR_GET_TIMING , .BR PR_GET_TIMERSLACK ,@@ -2074,6 +2217,24 @@ is .B PR_SVE_GET_VL and SVE is not available on this platform. .TP +.B EINVAL +.I option +is +.BR PR_SET_TAGGED_ADDR_CTRL +and the arguments are invalid or unsupported. +See the description of +.B PR_SET_TAGGED_ADDR_CTRL +above for details. +.TP +.B EINVAL +.I option +is +.BR PR_GET_TAGGED_ADDR_CTRL +and the arguments are invalid or unsupported. +See the description of +.B PR_GET_TAGGED_ADDR_CTRL +above for details. +.TP .B ENODEV .I option was
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/
Hi Dave,
Quoted 15 lines · Dave Martin
A bunch of updates to the prctl(2) man page to fill in missing prctls (mostly) up to Linux 5.6 (along with a few other tweaks and fixes).
Patches from the v2 series [1] that have been applied or rejected already have been dropped.
All that remain here now are the SVE and tagged address ABI controls for arm64.
Quoted 6 lines
Dave Martin (2):
prctl.2: Add SVE prctls (arm64)
prctl.2: Add tagged address ABI control prctls (arm64)man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 331 insertions(+)
Thanks. I've pushed these changes to master now.
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/
Quoted 18 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 15 lines · Dave Martin
A bunch of updates to the prctl(2) man page to fill in missing prctls (mostly) up to Linux 5.6 (along with a few other tweaks and fixes).
Patches from the v2 series [1] that have been applied or rejected already have been dropped.
All that remain here now are the SVE and tagged address ABI controls for arm64.
Quoted 7 lines
Quoted 6 lines
Dave Martin (2):
prctl.2: Add SVE prctls (arm64)
prctl.2: Add tagged address ABI control prctls (arm64)man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 331 insertions(+)Thanks. I've pushed these changes to master now.
Thanks -- btw I finally got around to reviewing master, and noted a few editorial changes that man-pages(7) does not make any statement about:
"arg1, arg2, and arg3"
Do you strictly prefer the command before "and" here?
Conventionally, the final comma would typically be omitted in prose, except where the list members are complex enough that the command is required to assist parsing. However, lists of formal arguments are not quite vanilla prose.
"Providing that" -> "Provided that"
Any particular rationale here?
"error EFOO" -> "the error EFOO"
Is this a rule, in general?
.IP \(bu 2
I assumed that specifying an explicit indentation amount would be fragile. Going with the default behaviour also tends to result in a more consistent appearance. Do you have any recommandations in this area?
Do you have rules about the order to use bullet symbols? I tend to avoid \(bu if possible, since while it's "correct", nroff can render it nastily as an unadorned letter "o" (e.g., with -Tascii or LC_CTYPE=C). This is particlarly annoying if the indent is <= 2, since then the "o" tends to be visually swallowed by the following text (i.e., to a casual glance it looks like a word, particlarly if the following text is not capitalised). Perhaps this is a bad glyph substitution decision in nroff rather than something that should be fixed in the man-pages source, but the man-pages source may be easier to fix...
There is already inconsistency here: there are may top-level lists using ".IP *" in prctl.2, and plenty of places where the default indentation is used.
Should any of these be written up in man-pages(7), or is there a checker than can detect them?
I wan't to minimise the amount of tweaking you have to do when merging patches.
Cheers
---Dave
A message that is not in the archive (sent off-list or not yet received): [email protected]
Hello Dave,
TL;DR: don't worry about the small stuff; I'm happy to do the minor edits given the high quality of your patches.
Quoted 31 lines · Dave Martin
Quoted 18 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 15 lines · Dave Martin
A bunch of updates to the prctl(2) man page to fill in missing prctls (mostly) up to Linux 5.6 (along with a few other tweaks and fixes).
Patches from the v2 series [1] that have been applied or rejected already have been dropped.
All that remain here now are the SVE and tagged address ABI controls for arm64.
Quoted 7 lines
Quoted 6 lines
Dave Martin (2):
prctl.2: Add SVE prctls (arm64)
prctl.2: Add tagged address ABI control prctls (arm64)man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 331 insertions(+)Thanks. I've pushed these changes to master now.
Thanks -- btw I finally got around to reviewing master, and noted a few editorial changes that man-pages(7) does not make any statement about:
Quoted 8 lines
"arg1, arg2, and arg3"
Do you strictly prefer the command before "and" here?
Conventionally, the final comma would typically be omitted in prose, except where the list members are complex enough that the command is required to assist parsing. However, lists of formal arguments are not quite vanilla prose.
There are two camps wrt that comma. I prefer the so-called Oxford comma convention, as shown above. man-pages uses it generally.
Quoted 3 lines
"Providing that" -> "Provided that"
Any particular rationale here?
Either would be fine; the past tense is just slightly better, to my ear.
Quoted 3 lines
"error EFOO" -> "the error EFOO"
Is this a rule, in general?
I think the change that you refer to was actually: "with EFOO" to "with the error EFOO". The former is just a little too brief, to my ear.
Quoted 18 lines
.IP \(bu 2
I assumed that specifying an explicit indentation amount would be fragile. Going with the default behaviour also tends to result in a more consistent appearance. Do you have any recommandations in this area?
Do you have rules about the order to use bullet symbols? I tend to avoid \(bu if possible, since while it's "correct", nroff can render it nastily as an unadorned letter "o" (e.g., with -Tascii or LC_CTYPE=C). This is particlarly annoying if the indent is <= 2, since then the "o" tends to be visually swallowed by the following text (i.e., to a casual glance it looks like a word, particlarly if the following text is not capitalised). Perhaps this is a bad glyph substitution decision in nroff rather than something that should be fixed in the man-pages source, but the man-pages source may be easier to fix...
Quoted 3 lines
There is already inconsistency here: there are may top-level lists using ".IP *" in prctl.2, and plenty of places where the default indentation is used.
I must admit that I'm in the process of rethinking bulleted lists, and I have not come to a conclusion (and that's why nothing is said in man-pages(7), and also why there is currently inconsistency).
Using .IP with the default indent (8n) results in a very deep indent between the glyph and the text, so it's not my preference.
Your note about the poor rendering with "-Tascii" is interesting. Perhaps ".IP \(bu 3" may be better. But, I really do not know: do people really render with "-Tascii" these days?
Quoted 2 lines
Should any of these be written up in man-pages(7), or is there a checker than can detect them?
Perhaps man-pages should say something about the Oxford comma.
Quoted 2 lines
I wan't to minimise the amount of tweaking you have to do when merging patches.
If every patch that I received was of the same quality as yours are, my life would be much easier. The tweaks are minimal work on my part. Don't worry. Just send me more patches :-).
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/
Quoted 85 lines · Michael Kerrisk (man-pages)
Hello Dave,
TL;DR: don't worry about the small stuff; I'm happy to do the minor edits given the high quality of your patches.
Quoted 31 lines · Dave Martin
Quoted 18 lines · Michael Kerrisk (man-pages)
Hi Dave,
Quoted 15 lines · Dave Martin
A bunch of updates to the prctl(2) man page to fill in missing prctls (mostly) up to Linux 5.6 (along with a few other tweaks and fixes).
Patches from the v2 series [1] that have been applied or rejected already have been dropped.
All that remain here now are the SVE and tagged address ABI controls for arm64.
Quoted 7 lines
Quoted 6 lines
Dave Martin (2):
prctl.2: Add SVE prctls (arm64)
prctl.2: Add tagged address ABI control prctls (arm64)man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 331 insertions(+)Thanks. I've pushed these changes to master now.
Thanks -- btw I finally got around to reviewing master, and noted a few editorial changes that man-pages(7) does not make any statement about:
Quoted 8 lines
"arg1, arg2, and arg3"
Do you strictly prefer the command before "and" here?
Conventionally, the final comma would typically be omitted in prose, except where the list members are complex enough that the command is required to assist parsing. However, lists of formal arguments are not quite vanilla prose.
There are two camps wrt that comma. I prefer the so-called Oxford comma convention, as shown above. man-pages uses it generally.
Quoted 3 lines
"Providing that" -> "Provided that"
Any particular rationale here?
Either would be fine; the past tense is just slightly better, to my ear.
Quoted 3 lines
"error EFOO" -> "the error EFOO"
Is this a rule, in general?
I think the change that you refer to was actually: "with EFOO" to "with the error EFOO". The former is just a little too brief, to my ear.
Quoted 18 lines
.IP \(bu 2
I assumed that specifying an explicit indentation amount would be fragile. Going with the default behaviour also tends to result in a more consistent appearance. Do you have any recommandations in this area?
Do you have rules about the order to use bullet symbols? I tend to avoid \(bu if possible, since while it's "correct", nroff can render it nastily as an unadorned letter "o" (e.g., with -Tascii or LC_CTYPE=C). This is particlarly annoying if the indent is <= 2, since then the "o" tends to be visually swallowed by the following text (i.e., to a casual glance it looks like a word, particlarly if the following text is not capitalised). Perhaps this is a bad glyph substitution decision in nroff rather than something that should be fixed in the man-pages source, but the man-pages source may be easier to fix...
Quoted 3 lines
There is already inconsistency here: there are may top-level lists using ".IP *" in prctl.2, and plenty of places where the default indentation is used.
Quoted 6 lines
I must admit that I'm in the process of rethinking bulleted lists, and I have not come to a conclusion (and that's why nothing is said in man-pages(7), and also why there is currently inconsistency).
Using .IP with the default indent (8n) results in a very deep indent between the glyph and the text, so it's not my preference.
Is it worth trying to change the default indent in the macro package, or will that just upset other people?
Quoted 3 lines
Your note about the poor rendering with "-Tascii" is interesting. Perhaps ".IP \(bu 3" may be better. But, I really do not know: do people really render with "-Tascii" these days?
Probably not, though it may happen depending on the locale and/or terminal type settings in minimal distro installs.
It's a minor annoyance at worst, and probably not worth fixing...
Quoted 4 lines
Quoted 2 lines
Should any of these be written up in man-pages(7), or is there a checker than can detect them?
Perhaps man-pages should say something about the Oxford comma.
Fair enough.
Quoted 6 lines
Quoted 2 lines
I wan't to minimise the amount of tweaking you have to do when merging patches.
If every patch that I received was of the same quality as yours are, my life would be much easier. The tweaks are minimal work on my part. Don't worry. Just send me more patches :-).
OK, I won't agonise too much over this, then.
Cheers
---Dave
Quoted 8 lines
Quoted 8 lines
Quoted 3 lines
There is already inconsistency here: there are may top-level lists using ".IP *" in prctl.2, and plenty of places where the default indentation is used.
I must admit that I'm in the process of rethinking bulleted lists, and I have not come to a conclusion (and that's why nothing is said in man-pages(7), and also why there is currently inconsistency).
Quoted 5 lines
Quoted 2 lines
Using .IP with the default indent (8n) results in a very deep indent between the glyph and the text, so it's not my preference.
Is it worth trying to change the default indent in the macro package, or will that just upset other people?
I imagine it would break other stuff.
Thanks,
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/
bulleted lists and indentation (was: prctl.2 man page updates for Linux 5.6)
[CC list trimmed]
Quoted 11 lines · Michael Kerrisk (man-pages)
Quoted 11 lines
Quoted 11 lines
Quoted 3 lines
There is already inconsistency here: there are may top-level lists using ".IP *" in prctl.2, and plenty of places where the default indentation is used.
I must admit that I'm in the process of rethinking bulleted lists, and I have not come to a conclusion (and that's why nothing is said in man-pages(7), and also why there is currently inconsistency).
Using .IP with the default indent (8n) results in a very deep indent between the glyph and the text, so it's not my preference.
Technically the indentation _amount_ is 7n in groff for nroff output (7.2n for troff). So with repeated indents you get text on columns 8, 15, 22, and so on (where the leftmost character cell is numbered 1).
Quoted 5 lines
Quoted 3 lines
Is it worth trying to change the default indent in the macro package, or will that just upset other people?
I imagine it would break other stuff.
In well-written man pages, I don't think it would, but it's still not worth doing within man pages themselves. However, a solution does exist that people can apply to their own environments, if their man pager uses groff as the typesetter (this is likely true of anybody reading this unless they know they use the mandoc program).
The same indentation value is used for multiple purposes in the groff implementation of the man macros, the language in which classical man pages are written. These purposes are:
1. The amount a standard paragraph (.PP, .LP, or .P) is indented from the left edge of the screen (where the section headings defined by .SH are aligned).
2. The amount a "relative indent" section is inset from the existing left margin. In other words, how much an .RS/.RE region lies "inboard" of the surrounding material if you don't give .RS an explicit argument.
3. The amount of space allocated to the tag in a tagged paragraph (the macros .TP and .TQ). (If the tag overruns this amount, it gets the output line to itself and the entire subsequent paragraph is set indented by this same amount.)
4. The amount of space by which an indented paragraph (.IP) is indented. (.IP takes an optional tag argument, and is ideal for itemized or enumerated lists.)
A nice feature of the above extensive re-use of the same parameter is that it pushes the man(7) language in the direction of being more semantic and less presentational. On the other hand, some people just don't like the resulting esthetics.
This parameter is a register called "IN". (There's one exception to this generality; the indent of a subsection is controlled by the register SN, and defaults to 3n.)
But rather than customizing each man page to the writer's preference, which will (and does) lead to an explosion of different conventions leading to an inconsistent user experience for readers of man pages from diverse sources, we can give tell the man macro package what we want this indentation amount to be.
You can edit your man.local file (on my Debian system, it is in /etc/groff/man.local), and add a line like this (without the leading tab):
.nr IN 4n
If you're practiced with the *roff language you can write conditionals to tune the application of this setting. Say I only want to change the IN register only if groff is my typesetter and if I'm rendering the page to "an nroff device" (a terminal, basically). I can do this:
.if \n(.g .if n .nr IN 4n
The first condition is probably slightly contrived because I'd be surprised if any non-groff typesetter opened /etc/groff/man.local to read it, but I don't want to come across as unecumenical; there are users out there of Heirloom Doctools troff, Plan 9 troff, and neatroff.
I'm attaching an example man page to demonstrate the above. If you use Colin Watson's man-db you can view it directly with "man -l". I put the register tweaking directly at the top of the page to make it easy for people to experiment but *PLEASE* don't do this in actual man pages. To reiterate my earlier point: we want to empower the _reader_ to configure the indentation in a way that pleases them, not encourage a hundred different man page writers to subject the rest of the world to their varied and conflicting preferences.
Regards,
Branden