prctl.2: Document Syscall User Dispatch
PATCH v3 1/1 prctl.2: Document Syscall User Dispatch
---
Changes since v2:
(suggested by Alejandro Colomar)
- selective -> selectively
- Add missing oxford comma.
Changes since v1:
(suggested by Alejandro Colomar)
- Use semantic lines
- Fix usage of .{B|I}R and .{B|I}
- Don't format literals
- Fix preferred spelling of userspace
- Fix case of word
--- man2/prctl.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+)
man2/prctl.2 +100 -0
@@ -1533,6 +1533,78 @@ For more information, see the kernel source file (or .I Documentation/arm64/sve.txt before Linux 5.3). +.TP +.\" prctl PR_SET_SYSCALL_USER_DISPATCH +.\" commit 1446e1df9eb183fdf81c3f0715402f1d7595d4 +.BR PR_SET_SYSCALL_USER_DISPATCH " (since Linux 5.11, x86 only)" +.IP +Configure the Syscall User Dispatch mechanism +for the calling thread, +to selectively intercept system calls +and dispatch them back to user space through +.IR SIGSYS . +.IP +The current Syscall User Dispatch mode is selected via +.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 +.I arg2 +set to +.BR PR_SYS_DISPATCH_ON , +.I arg3 +and +.I arg4 +respectively identify the +.I offset +and +.I length +of a memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable. +.I arg5 +points to a char-sized variable +that is a fast switch to enable/disable the mechanism +without invoking the kernel. +The variable pointed by +.I arg5 +can either be set to +.B PR_SYS_DISPATCH_ON +to enable the mechanism +or to +.B PR_SYS_DISPATCH_OFF +to temporarily disable it. +Any other value will fail the application +with a +.IR SIGSYS . +.IP +When a system call is intercepted, +.I SIGSYS +is raised with +.I si_code +set to +.BR SYS_USER_DISPATCH . +.IP +When +.I arg2 +is set to +.BR PR_SYS_DISPATCH_OFF , +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). +.IP +For more information, +see the kernel source file +.IR Documentation/admin-guide/syscall-user-dispatch.rst .\" prctl PR_SET_TAGGED_ADDR_CTRL .\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d .TP
@@ -2000,6 +2072,14 @@ and .I arg3 is an invalid address. .TP +.B EFAULT +.I option +is +.B PR_SET_SYSCALL_USER_DISPATCH +and +.I arg5 +has an invalid address. +.TP .B EINVAL The value of .I option
@@ -2229,6 +2309,26 @@ 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 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
Signature · 1 line
2.29.2
Quoted 27 lines · Gabriel Krisman Bertazi
Signed-off-by Gabriel Krisman Bertazi <[email protected]>---
Changes since v2:
(suggested by Alejandro Colomar)
- selective -> selectively
- Add missing oxford comma.Changes since v1:
(suggested by Alejandro Colomar)
- Use semantic lines
- Fix usage of .{B|I}R and .{B|I}
- Don't format literals
- Fix preferred spelling of userspace
- Fix case of word--- man2/prctl.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+)man2/prctl.2 +0
-0@@ -1533,6 +1533,78 @@ For more information, see the kernel source file (or .I Documentation/arm64/sve.txt before Linux 5.3).
man2/prctl.2 For more information, see the kernel source file · line 1545
Quoted 10 lines
man2/prctl.2 +10
-0+.TP +.\" prctl PR_SET_SYSCALL_USER_DISPATCH +.\" commit 1446e1df9eb183fdf81c3f0715402f1d7595d4 +.BR PR_SET_SYSCALL_USER_DISPATCH " (since Linux 5.11, x86 only)" +.IP +Configure the Syscall User Dispatch mechanism +for the calling thread, +to selectively intercept system calls +and dispatch them back to user space through +.IR SIGSYS .
s/IR/BR/
I think a bit more explanation would help here. Could you add a few sentences to explain what "dispatch back to user space through SIGSYS" means?
man2/prctl.2 For more information, see the kernel source file · line 1554
Quoted 9 lines
man2/prctl.2 +9
-0+.IP +The current Syscall User Dispatch mode is selected via +.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.
By the way, why is there no PR_*G*ET_SYSCALL_USER_DISPATCH?
Quoted 5 lines
man2/prctl.2 +5
-0+.IP +With +.I arg2 +set to +.BR PR_SYS_DISPATCH_ON ,
man2/prctl.2 For more information, see the kernel source file · line 1569
Quoted 10 lines
man2/prctl.2 +10
-0+.I arg3 +and +.I arg4 +respectively identify the +.I offset +and +.I length +of a memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable.
Can there be more than one of these regions?
The text should be explicit about this, I think.
Quoted 5 lines
man2/prctl.2 +5
-0+.I arg5 +points to a char-sized variable +that is a fast switch to enable/disable the mechanism +without invoking the kernel. +The variable pointed by
man2/prctl.2 For more information, see the kernel source file · line 1584
Quoted 10 lines
man2/prctl.2 +10
-0+.I arg5 +can either be set to +.B PR_SYS_DISPATCH_ON +to enable the mechanism +or to +.B PR_SYS_DISPATCH_OFF +to temporarily disable it. +Any other value will fail the application +with a +.IR SIGSYS .
How/when does that failure occur? At the time of the prctl() call, I presume? What if the caller later sets the variable pointed to by arg5 to another value?
Quoted 44 lines
man2/prctl.2 +31
-0+.IP +When a system call is intercepted, +.I SIGSYS +is raised with +.I si_code +set to +.BR SYS_USER_DISPATCH . +.IP +When +.I arg2 +is set to +.BR PR_SYS_DISPATCH_OFF , +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). +.IP +For more information, +see the kernel source file +.IR Documentation/admin-guide/syscall-user-dispatch.rst .\" prctl PR_SET_TAGGED_ADDR_CTRL .\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d .TP@@ -2000,6 +2072,14 @@ and .I arg3 is an invalid address. .TP +.B EFAULT +.I option +is +.B PR_SET_SYSCALL_USER_DISPATCH +and +.I arg5 +has an invalid address. +.TP .B EINVAL The value of .I option@@ -2229,6 +2309,26 @@ is and SVE is not available on this platform. .TP
man2/prctl.2 is · line 2320
Quoted 10 lines
man2/prctl.2 +9
-0.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 0;
s/and/and the/
man2/prctl.2 is · line 2325
Quoted 5 lines
man2/prctl.2 +5
-0+.IP * 3 +.I arg2 +is +.B PR_SYS_DISPATCH_ON +and the memory region provided is invalid;
Please define "invalid"
man2/prctl.2 is · line 2334
Quoted 9 lines
man2/prctl.2 +6
-0+.IP * 3 +.I arg2 +is invalid. +.RE +.TP +.B EINVAL .I option is .BR PR_SET_TAGGED_ADDR_CTRL
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/
Quoted 45 lines · Michael Kerrisk (man-pages)
Quoted 27 lines · Gabriel Krisman Bertazi
Signed-off-by Gabriel Krisman Bertazi <[email protected]>---
Changes since v2:
(suggested by Alejandro Colomar)
- selective -> selectively
- Add missing oxford comma.Changes since v1:
(suggested by Alejandro Colomar)
- Use semantic lines
- Fix usage of .{B|I}R and .{B|I}
- Don't format literals
- Fix preferred spelling of userspace
- Fix case of word--- man2/prctl.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+)man2/prctl.2 +0
-0@@ -1533,6 +1533,78 @@ For more information, see the kernel source file (or .I Documentation/arm64/sve.txt before Linux 5.3).man2/prctl.2 For more information, see the kernel source file · line 1545
Quoted 10 lines
man2/prctl.2 +10
-0+.TP +.\" prctl PR_SET_SYSCALL_USER_DISPATCH +.\" commit 1446e1df9eb183fdf81c3f0715402f1d7595d4 +.BR PR_SET_SYSCALL_USER_DISPATCH " (since Linux 5.11, x86 only)" +.IP +Configure the Syscall User Dispatch mechanism +for the calling thread, +to selectively intercept system calls +and dispatch them back to user space through +.IR SIGSYS .s/IR/BR/
I think a bit more explanation would help here. Could you add a few sentences to explain what "dispatch back to user space through SIGSYS" means?
Quoted 11 lines
man2/prctl.2 For more information, see the kernel source file · line 1554
Quoted 9 lines
man2/prctl.2 +9
-0+.IP +The current Syscall User Dispatch mode is selected via +.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.By the way, why is there no PR_*G*ET_SYSCALL_USER_DISPATCH?
Thanks for the feedback. I will prepare a new version.
Just to clarify this point, there isn't a strict reason why I didn't implement the PR_GET_* , I just didn't see much value in adding it because, 1) the same thread that enables the feature is the only affected by it, as it is reset across fork/clone, and (2) there isn't the case where a program inherit this setting from the parent, as it doesn't cross exec*(2).
Therefore, every case where a getter would be used, can just be solved in userspace quite easily, IMO.
Quoted 30 lines
Quoted 5 lines
man2/prctl.2 +5
-0+.IP +With +.I arg2 +set to +.BR PR_SYS_DISPATCH_ON ,man2/prctl.2 For more information, see the kernel source file · line 1569
Quoted 10 lines
man2/prctl.2 +10
-0+.I arg3 +and +.I arg4 +respectively identify the +.I offset +and +.I length +of a memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable.Can there be more than one of these regions?
The text should be explicit about this, I think.Quoted 11 lines
man2/prctl.2 +11
-0+.I arg5 +points to a char-sized variable +that is a fast switch to enable/disable the mechanism +without invoking the kernel. +The variable pointed by +.I arg5 +can either be set to +.B PR_SYS_DISPATCH_ON +to enable the mechanism +or to +.B PR_SYS_DISPATCH_OFF
Quoted 8 lines
man2/prctl.2 For more information, see the kernel source file · line 1584
Quoted 4 lines
man2/prctl.2 +4
-0+to temporarily disable it. +Any other value will fail the application +with a +.IR SIGSYS .How/when does that failure occur? At the time of the
prctl()call, I presume? What if the caller later sets the variable pointed to by arg5 to another value?
Actually, this happens at syscall-interception time. So you can have a bogus value in *arg5, as long as you don't invoke a syscall with a bad *arg5. Will properly document it.
Thanks,
Signature · 1 line
Gabriel Krisman Bertazi