Debian Codegraph @

upstream/debian-unstable/man2/PR_SET_SYSCALL_USER_DISPATCH.2const

raw
1 .\" Copyright 2021, Gabriel Krisman Bertazi <[email protected]>
2 .\" Copyright 2021, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH PR_SET_SYSCALL_USER_DISPATCH 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 PR_SET_SYSCALL_USER_DISPATCH
10 \-
11 set the system-call user dispatch mechanism for the calling thread
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <linux/prctl.h>" " /* Definition of " PR_* " constants */"
18 .B #include <sys/prctl.h>
19 .P
20 .BI "int prctl(PR_SET_SYSCALL_USER_DISPATCH, long " op ", ...);"
21 .P
22 .B int prctl(PR_SET_SYSCALL_USER_DISPATCH, PR_SYS_DISPATCH_ON,
23 .BI " unsigned long " off ", unsigned long " size ", int8_t *" switch );
24 .B int prctl(PR_SET_SYSCALL_USER_DISPATCH, PR_SYS_DISPATCH_OFF, 0L, 0L, 0L);
25 .fi
26 .SH DESCRIPTION
27 Configure the Syscall User Dispatch mechanism
28 for the calling thread.
29 This mechanism allows an application
30 to selectively intercept system calls
31 so that they can be handled within the application itself.
32 Interception takes the form of a thread-directed
33 .B SIGSYS
34 signal that is delivered to the thread
35 when it makes a system call.
36 If intercepted,
37 the system call is not executed by the kernel.
38 .TP
39 .B PR_SYS_DISPATCH_ON
40 Enable this mechanism.
41 .IP
42 Once enabled, further system calls will be selectively intercepted,
43 depending on a control variable provided by user space.
44 In this case,
45 .I off
46 and
47 .I size
48 respectively identify the
49 offset
50 and
51 size
52 of a single contiguous memory region in the process address space
53 from where system calls are always allowed to be executed,
54 regardless of the control variable.
55 (Typically, this area would include the area of memory
56 containing the C library.)
57 .IP
58 .I switch
59 points to a variable
60 that is a fast switch to allow/block system call execution
61 without the overhead of doing another system call
62 to re-configure Syscall User Dispatch.
63 This control variable can either be set to
64 .B SYSCALL_DISPATCH_FILTER_BLOCK
65 to block system calls from executing
66 or to
67 .B SYSCALL_DISPATCH_FILTER_ALLOW
68 to temporarily allow them to be executed.
69 This value is checked by the kernel
70 on every system call entry,
71 and any unexpected value will raise
72 an uncatchable
73 .B SIGSYS
74 at that time,
75 killing the application.
76 .IP
77 When a system call is intercepted,
78 the kernel sends a thread-directed
79 .B SIGSYS
80 signal to the triggering thread.
81 Various fields will be set in the
82 .I siginfo_t
83 structure (see
84 .BR sigaction (2))
85 associated with the signal:
86 .RS
87 .IP \[bu] 3
88 .I si_signo
89 will contain
90 .BR SIGSYS .
91 .IP \[bu]
92 .I si_call_addr
93 will show the address of the system call instruction.
94 .IP \[bu]
95 .I si_syscall
96 and
97 .I si_arch
98 will indicate which system call was attempted.
99 .IP \[bu]
100 .I si_code
101 will contain
102 .BR SYS_USER_DISPATCH .
103 .IP \[bu]
104 .I si_errno
105 will be set to 0.
106 .RE
107 .IP
108 The program counter will be as though the system call happened
109 (i.e., the program counter will not point to the system call instruction).
110 .IP
111 When the signal handler returns to the kernel,
112 the system call completes immediately
113 and returns to the calling thread,
114 without actually being executed.
115 If necessary
116 (i.e., when emulating the system call on user space.),
117 the signal handler should set the system call return value
118 to a sane value,
119 by modifying the register context stored in the
120 .I ucontext
121 argument of the signal handler.
122 See
123 .BR sigaction (2),
124 .BR sigreturn (2),
125 and
126 .BR getcontext (3)
127 for more information.
128 .TP
129 .B PR_SYS_DISPATCH_OFF
130 Syscall User Dispatch is disabled for that thread.
131 .P
132 The setting is not preserved across
133 .BR fork (2),
134 .BR clone (2),
135 or
136 .BR execve (2).
137 .SH RETURN VALUE
138 On success,
139 0 is returned.
140 On error, \-1 is returned, and
141 .I errno
142 is set to indicate the error.
143 .SH ERRORS
144 .TP
145 .B EFAULT
146 .I switch
147 is an invalid address.
148 .TP
149 .B EINVAL
150 .I op
151 is
152 .B PR_SYS_DISPATCH_ON
153 and the memory range specified is outside the
154 address space of the process.
155 .TP
156 .B EINVAL
157 .I op
158 is invalid.
159 .SH STANDARDS
160 Linux.
161 x86 only.
162 .SH HISTORY
163 .\" commit 1446e1df9eb183fdf81c3f0715402f1d7595d4
164 Linux 5.11 (x86).
165 .SH SEE ALSO
166 .BR prctl (2)
167 .P
168 For more information,
169 see the kernel source file
170 .I Documentation/\:admin\-guide/\:syscall\-user\-dispatch.rst