* Re: [PATCH] prctl.2: Document Syscall User Dispatch
2020-12-19 4:10 [PATCH] prctl.2: Document Syscall User Dispatch Gabriel Krisman Bertazi
@ 2020-12-19 15:01 ` Alejandro Colomar (man-pages)
2020-12-21 16:38 ` Gabriel Krisman Bertazi
0 siblings, 1 reply; 3+ messages in thread
From: Alejandro Colomar (man-pages) @ 2020-12-19 15:01 UTC (permalink / raw)
To: Gabriel Krisman Bertazi, mtk.manpages; +Cc: linux-man
Hi Gabriel,
Thanks for the page!
Please see some comments below.
Thanks,
Alex
On 12/19/20 5:10 AM, Gabriel Krisman Bertazi wrote:
> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
> ---
> man2/prctl.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 93 insertions(+)
>
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index f25f05fdb593..2e82c73c10c2 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1533,6 +1533,70 @@ For more information, see the kernel source file
> (or
> .I Documentation/arm64/sve.txt
> before Linux 5.3).
> +.TP
> +.\"commit 1446e1df9eb183fdf81c3f0715402f1d7595d4cb
> +.BR PR_SET_SYSCALL_USER_DISPATCH " (Since Linux 5.11, x86 only)"
s/Since/since
rationale:
$ grep -r '(Since Linux' man? |wc -l
48
$ grep -r '(since Linux' man? |wc -l
1286
> +.IP
> +Configure the Syscall User Dispatch mechanism for the calling thread, to
See:
$ man 7 man-pages |sed -n '/Use semantic newlines/,/^$/p'
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, and long sentences should split into lines at
clause breaks (commas, semicolons, colons, and so on). This
convention, sometimes known as "semantic newlines", makes it
easier to see the effect of patches, which often operate at the
level of individual sentences or sentence clauses.
> +selective intercept system calls and dispatch them back to userspace
s/userspace/user space/
Rationale:
$ man 7 man-pages |sed -n '/Preferred/,/user space/p'
Preferred terms
The following table lists some preferred terms to use in man
pages, mainly to ensure consistency across pages.
Term Avoid using Notes
────────────────────────────────────────────────────────────────────────────────────────────────────
bit mask bitmask
built-in builtin
Epoch epoch For the UNIX
Epoch (00:00:00, 1 Jan 1970 UTC)
filename file name
filesystem file system
hostname host name
inode i-node
lowercase lower case, lower-case
nonzero non-zero
pathname path name
pseudoterminal pseudo-terminal
privileged port reserved port, system port
real-time realtime, real time
run time runtime
saved set-group-ID saved group ID, saved set-GID
saved set-user-ID saved user ID, saved set-UID
set-group-ID set-GID, setgid
set-user-ID set-UID, setuid
superuser super user, super-user
superblock super block, super-block
timestamp time stamp
timezone time zone
uppercase upper case, upper-case
usable useable
user space userspace
> +through
> +.IR SIGSYS .
> +.IP
> +The current Syscall User Dispatch mode is selected via
> +.IR "arg2",
.IR arg2 ,
> +which can either be set to
> +.B PR_SYS_DISPATCH_ON
> +to enable the feature, or to
> +.B PR_SYS_DISPATCH_OFF
> +to turn it off.
> +.IP
> +With
> +.IR "arg2"
.I arg2
> +set to
> +.BR PR_SYS_DISPATCH_ON ,
> +.IR "arg3"
.I arg3
> +and
> +.I "arg4"
tr -d '"'
> +respectively identify the
> +.I offset
> +and
> +.I length
> +of a memory region in the process map from where system calls are always
See semantic newlines above.
> +allowed to be executed, regardless of the switch variable.
> +.I "arg5"
tr -d '"'
> +points to a char-sized variable that is a fast switch to enable/disable> +the mechanism without invoking the kernel.
> +.I "arg5"
tr -d '"'
> +can be set to either
> +.BR PR_SYS_DISPATCH_ON
s/.BR/.B/
> +to enable the mechanism or to
> +.BR PR_SYS_DISPATCH_OFF
s/.BR/.B
> +to temporarily disable it. Any other value will fail the application> +with a
See semantic newlines above.
> +.IR SIGSYS .
> +.IP
> +When a system call is intercepted, a
> +.I SIGSYS
> +is raised with
> +.I si_code
> +set to
> +.B SYS_USER_DISPATCH.
.BR SYS_USER_DISPATCH .
> +.IP
> +When
> +.I "arg2"
tr -d '"'
> +is set to
> +.BR PR_SYS_DISPATCH_OFF ,
> +the remaining arguments must be set to
> +.BR 0 .
Literals are not (usually) formatted.
[
the remaining arguments must be set to 0.
]
> +.IP
> +The setting is not preserved across
> +.BR fork (2),
> +.BR clone (2)
> +or
> +.BR execve (2) .
s/(2) ./(2)./
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/admin-guide/syscall-user-dispatch.rst
s/.IR/.I/
Could you add
> .\" prctl PR_SET_TAGGED_ADDR_CTRL
> .\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> .TP
> @@ -2000,6 +2064,14 @@ and
> .I arg3
> is an invalid address.
> .TP
> +.B EFAULT
> +.I option
> +is
> +.BR PR_SET_SYSCALL_USER_DISPATCH
s/.BR/.B/
> +and
> +.I arg5
> +has an invalid address.
> +.TP
> .B EINVAL
> The value of
> .I option
> @@ -2229,6 +2301,27 @@ is
> and SVE is not available on this platform.
> .TP
> .B EINVAL
> +.I option is
> +.B PR_SET_SYSCALL_USER_DISPATCH
> +and one of the following is true:
> +.RS
> +.IP * 3
> +.I arg2
> +is
> +.B PR_SYS_DISPATCH_OFF
> +and remaining arguments are not
> +.BR 0.
and remaining arguments are not 0.
> +.IP * 3
> +.I arg2
> +is
> +.B PR_SYS_DISPATCH_ON
> +and the memory region provided is invalid.> +.IP * 3
> +.I arg2
> +is invalid.
> +.RE
> +.TP
> +.B EINVAL
> .I option
> is
> .BR PR_SET_TAGGED_ADDR_CTRL
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 3+ messages in thread