Skip to contentSkip to conversation

prctl.2: Document Syscall User Dispatch

PATCH Superseded Gabriel Krisman Bertazi 3 participants 7 messages Dec 23, 2020 – Dec 28, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v5 of 8 Superseded Latest is v8 →

lore
Share & tools
lore
#0 lore raw

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
index f25f05fdb593..0d26fdcb5e3d 100644
@@ -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
#1 lore raw

Hello Gabriel,

Thanks for the revisions!

Quoted 74 lines · Gabriel Krisman Bertazi

---
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
index f25f05fdb593..0d26fdcb5e3d 100644
@@ -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/
#2 lore raw

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/
#3 lore raw

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
+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/)./.)/

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/
#4 lore raw
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
+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/)./.)/

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/
#5 lore raw
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
+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/)./.)/

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

#6 lore raw
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
+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/)./.)/

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