prctl.2: Document Syscall User Dispatch
PATCH v5 1/1 prctl.2: Document Syscall User Dispatch
---
Changes since v4:
(suggested by Michael Kerrisk)
- Modify explanation of what dispatch to user space means.
- Drop references to emulation.
- Document suggestion about placing libc in allowed-region.
- Comment about avoiding syscall cost.
Changes since v3:
(suggested by Michael Kerrisk)
- Explain what dispatch to user space means.
- Document the fact that the memory region is a single consecutive range.
- Explain failure if *arg5 is set to a bad value.
- fix english typo.
- Define what 'invalid memory region' means.
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 | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+)
man2/prctl.2 +116 -0
@@ -1533,6 +1533,92 @@ 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. +This mechanism allows an application +to selectively intercept system calls +so that they can be handled within the application itself. +Interception takes the form of a thread-directed +.B SIGSYS +signal that is delivered to the thread +when it makes a system call. +If intercepted, +the system call is not executed by the kernel. +.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 +When +.I arg2 +is set to +.BR PR_SYS_DISPATCH_ON , +.I arg3 +and +.I arg4 +respectively identify the +.I offset +and +.I length +of a single contiguous memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable +(Typically, this area would include the area of memory +containing the C library). +.I arg5 +points to a char-sized variable +that is a fast switch to enable/disable the mechanism +without the overhead of doing a system call. +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. +The value pointed by +.B arg5 +is checked by the kernel +on every system call entry, +and any unexpected value will raise +an uncatchable +.B SIGSYS +at that time, +killing the application. +.PI +When a system call is intercepted, +.B 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 +2086,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
@@ -2231,6 +2325,28 @@ and SVE is not available on this platform. .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 the remaining arguments are not 0; +.IP * 3 +.I arg2 +is +.B PR_SYS_DISPATCH_ON +and the memory range specified is outside the +address space of the process. +.IP * 3 +.I arg2 +is invalid. +.RE +.TP +.B EINVAL +.I option +is .BR PR_SET_TAGGED_ADDR_CTRL and the arguments are invalid or unsupported. See the description of
Signature · 1 line
2.29.2
Hello Gabriel,
Thanks for the revisions!
Quoted 74 lines · Gabriel Krisman Bertazi
Signed-off-by Gabriel Krisman Bertazi <[email protected]>---
Changes since v4:
(suggested by Michael Kerrisk)
- Modify explanation of what dispatch to user space means.
- Drop references to emulation.
- Document suggestion about placing libc in allowed-region.
- Comment about avoiding syscall cost.
Changes since v3:
(suggested by Michael Kerrisk)
- Explain what dispatch to user space means.
- Document the fact that the memory region is a single consecutive range.
- Explain failure if *arg5 is set to a bad value.
- fix english typo.
- Define what 'invalid memory region' means.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 | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+)man2/prctl.2 +32
-0@@ -1533,6 +1533,92 @@ 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. +This mechanism allows an application +to selectively intercept system calls +so that they can be handled within the application itself. +Interception takes the form of a thread-directed +.B SIGSYS +signal that is delivered to the thread +when it makes a system call. +If intercepted, +the system call is not executed by the kernel. +.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 +When +.I arg2 +is set to +.BR PR_SYS_DISPATCH_ON , +.I arg3 +and
man2/prctl.2 For more information, see the kernel source file · line 1577
Quoted 10 lines
man2/prctl.2 +10
-0+.I arg4 +respectively identify the +.I offset +and +.I length +of a single contiguous memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable +(Typically, this area would include the area of memory +containing the C library).
s/)./.)/
man2/prctl.2 For more information, see the kernel source file · line 1582
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 the overhead of doing a system call. +The variable pointed by
s/pointed/pointed to/
Quoted 13 lines
man2/prctl.2 +13
-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. +The value pointed by +.B arg5 +is checked by the kernel +on every system call entry, +and any unexpected value will raise +an uncatchable
man2/prctl.2 For more information, see the kernel source file · line 1605
Quoted 10 lines
man2/prctl.2 +10
-0+.B SIGSYS +at that time, +killing the application. +.PI +When a system call is intercepted, +.B SIGSYS +is raised with +.I si_code +set to +.BR SYS_USER_DISPATCH .
Shouldn't we mention here also: si_call_addr, si_arch, and si_syscall?
So, by this point, there still seems to be info lacking. When the SIGSYS handler returns, what happens? In the emulation use-case, what will the return value of the system call look like? Can that return value be defined from the SISGSYS handler, and if so, how? I couldn't really see any answers in Documentation/admin-guide/syscall-user-dispatch.rst
and I think there should be at least some of this info in the manual page.
Cheers,
Michael
Quoted 64 lines
man2/prctl.2 +46
-0+.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 +2086,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@@ -2231,6 +2325,28 @@ and SVE is not available on this platform. .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 the remaining arguments are not 0; +.IP * 3 +.I arg2 +is +.B PR_SYS_DISPATCH_ON +and the memory range specified is outside the +address space of the process. +.IP * 3 +.I arg2 +is invalid. +.RE +.TP +.B EINVAL +.I option +is .BR PR_SET_TAGGED_ADDR_CTRL and the arguments are invalid or unsupported. See the description of
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 Michael & Gabriel,
I disagree on a comment; see below.
Quoted 4 lines · Michael Kerrisk (man-pages)
Hello Gabriel,
Thanks for the revisions!
[...]
Quoted 11 lines
Quoted 11 lines
+.IP
man2/prctl.2 +10
-0+When +.I arg2 +is set to +.BR PR_SYS_DISPATCH_ON , +.I arg3 +and +.I arg4 +respectively identify the +.I offset +and
Quoted 8 lines
man2/prctl.2 For more information, see the kernel source file · line 1577
Quoted 6 lines
+.I length
man2/prctl.2 +5
-0+of a single contiguous memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable +(Typically, this area would include the area of memory +containing the C library).s/)./.)/
That point is ending the full sentence starting at 'When', not just the sentence in parentheses.
See <https://www.thepunctuationguide.com/terminal-points.html>.
Quoting that, "The main sentence takes a period outside the closing parenthesis no matter what punctuation is included inside the parenthetical element.". So that you should be able to: s/(.*)//
s/)./.)./ would be more correct, but I think ').' is enough. See my quotation above, which is a similar example :)
I'd also s/Typically/typically/
Your thoughts?
Thanks,
Alex
Quoted 6 lines
Quoted 6 lines
+.I arg5
man2/prctl.2 +4
-0+points to a char-sized variable +that is a fast switch to enable/disable the mechanism +without the overhead of doing a system call. +The variable pointed by
Signature · 3 lines
Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Hi Alex,
Quoted 31 lines · Alejandro Colomar (man-pages)
Hi Michael & Gabriel,
I disagree on a comment; see below.
Quoted 4 lines · Michael Kerrisk (man-pages)
Hello Gabriel,
Thanks for the revisions!
[...]
Quoted 11 lines
Quoted 11 lines
+.IP
man2/prctl.2 +10
-0+When +.I arg2 +is set to +.BR PR_SYS_DISPATCH_ON , +.I arg3 +and +.I arg4 +respectively identify the +.I offset +andQuoted 8 lines
man2/prctl.2 For more information, see the kernel source file · line 1577
Quoted 6 lines
+.I length
man2/prctl.2 +5
-0+of a single contiguous memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable +(Typically, this area would include the area of memory +containing the C library).s/)./.)/
Quoted 1 line
That point is ending the full sentence starting at 'When',
I see it the other. The piece in parentheses is a free-standing idea that should be (parenthetical) sentence on its own.
But, if that was not the case, your points below would hold.
Thanks,
Michael
Quoted 31 lines
not just the
sentence in parentheses.See <https://www.thepunctuationguide.com/terminal-points.html>.
Quoting that, "The main sentence takes a period outside the closing parenthesis no matter what punctuation is included inside the parenthetical element.". So that you should be able to: s/(.*)//
s/)./.)./ would be more correct, but I think ').' is enough. See my quotation above, which is a similar example :)
I'd also s/Typically/typically/
Your thoughts?
Thanks,
Alex
Quoted 6 lines
man2/prctl.2 For more information, see the kernel source file · line 1582
Quoted 6 lines
+.I arg5
man2/prctl.2 +4
-0+points to a char-sized variable +that is a fast switch to enable/disable the mechanism +without the overhead of doing a system call. +The variable pointed by--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
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 35 lines · Michael Kerrisk (man-pages)
Hi Alex,
Quoted 31 lines · Alejandro Colomar (man-pages)
Hi Michael & Gabriel,
I disagree on a comment; see below.
Quoted 4 lines · Michael Kerrisk (man-pages)
Hello Gabriel,
Thanks for the revisions!
[...]
Quoted 19 lines
Quoted 7 lines
+.IP
man2/prctl.2 +6
-0+When +.I arg2 +is set to +.BR PR_SYS_DISPATCH_ON , +.I arg3 +andman2/prctl.2 For more information, see the kernel source file · line 1577
Quoted 10 lines
man2/prctl.2 +10
-0+.I arg4 +respectively identify the +.I offset +and +.I length +of a single contiguous memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable +(Typically, this area would include the area of memory +containing the C library).s/)./.)/
Quoted 6 lines
Quoted 1 line
That point is ending the full sentence starting at 'When',
I see it the other. The piece in parentheses is a free-standing idea that should be (parenthetical) sentence on its own.
But, if that was not the case, your points below would hold.
Hi Michael,
I see; but there still isn't any separator between '... switch variable', and 'arg5 points to ...'.
Would you then do?:
[
+regardless of the switch variable_._
]
Or what?
Thanks,
Alex
Quoted 40 lines
Thanks,
Michael
Quoted 31 lines
not just the
sentence in parentheses.See <https://www.thepunctuationguide.com/terminal-points.html>.
Quoting that, "The main sentence takes a period outside the closing parenthesis no matter what punctuation is included inside the parenthetical element.". So that you should be able to: s/(.*)//
s/)./.)./ would be more correct, but I think ').' is enough. See my quotation above, which is a similar example :)
I'd also s/Typically/typically/
Your thoughts?
Thanks,
Alex
Quoted 6 lines
man2/prctl.2 For more information, see the kernel source file · line 1582
Quoted 6 lines
+.I arg5
man2/prctl.2 +4
-0+points to a char-sized variable +that is a fast switch to enable/disable the mechanism +without the overhead of doing a system call. +The variable pointed by--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
Signature · 3 lines
Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Quoted 51 lines · Alejandro Colomar (man-pages)
Quoted 35 lines · Michael Kerrisk (man-pages)
Hi Alex,
Quoted 31 lines · Alejandro Colomar (man-pages)
Hi Michael & Gabriel,
I disagree on a comment; see below.
Quoted 4 lines · Michael Kerrisk (man-pages)
Hello Gabriel,
Thanks for the revisions!
[...]
Quoted 19 lines
Quoted 7 lines
+.IP
man2/prctl.2 +6
-0+When +.I arg2 +is set to +.BR PR_SYS_DISPATCH_ON , +.I arg3 +andman2/prctl.2 For more information, see the kernel source file · line 1577
Quoted 10 lines
man2/prctl.2 +10
-0+.I arg4 +respectively identify the +.I offset +and +.I length +of a single contiguous memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable +(Typically, this area would include the area of memory +containing the C library).s/)./.)/
Quoted 6 lines
Quoted 1 line
That point is ending the full sentence starting at 'When',
I see it the other. The piece in parentheses is a free-standing idea that should be (parenthetical) sentence on its own.
But, if that was not the case, your points below would hold.
Hi Michael,
I see; but there still isn't any separator between '... switch variable', and 'arg5 points to ...'.
Quoted 7 lines
Would you then do?:
[
+regardless of the switch variable_._
]Or what?
Oh yes. I missed that. That period also needs to be added!
Cheers,
Michael
Quoted 55 lines · Michael Kerrisk (man-pages)
Quoted 53 lines · Alejandro Colomar (man-pages)
Quoted 35 lines · Michael Kerrisk (man-pages)
Hi Alex,
Quoted 31 lines · Alejandro Colomar (man-pages)
Hi Michael & Gabriel,
I disagree on a comment; see below.
Quoted 4 lines · Michael Kerrisk (man-pages)
Hello Gabriel,
Thanks for the revisions!
[...]
Quoted 19 lines
Quoted 7 lines
+.IP
man2/prctl.2 +6
-0+When +.I arg2 +is set to +.BR PR_SYS_DISPATCH_ON , +.I arg3 +andman2/prctl.2 For more information, see the kernel source file · line 1577
Quoted 10 lines
man2/prctl.2 +10
-0+.I arg4 +respectively identify the +.I offset +and +.I length +of a single contiguous memory region in the process map +from where system calls are always allowed to be executed, +regardless of the switch variable +(Typically, this area would include the area of memory +containing the C library).s/)./.)/
Quoted 6 lines
Quoted 1 line
That point is ending the full sentence starting at 'When',
I see it the other. The piece in parentheses is a free-standing idea that should be (parenthetical) sentence on its own.
But, if that was not the case, your points below would hold.
Hi Michael,
I see; but there still isn't any separator between '... switch variable', and 'arg5 points to ...'.
Would you then do?:
Quoted 8 lines
Quoted 5 lines
[
+regardless of the switch variable_._
]Or what?
Oh yes. I missed that. That period also needs to be added!
Which one?
Quoted 1 line
+regardless of the switch variable_._
or
Quoted 2 lines
I see; but there still isn't any separator between '... switch variable', and 'arg5 points to ...'.
which would be .).
Signature · 1 line
Gabriel Krisman Bertazi