Ubuntu Manpage: PR_SET_SYSCALL_USER_DISPATCH - set the system-call user dispatch mechanism for the calling thread

name
library
synopsis
description
return value
errors
standards
history
see also

plucky (2) PR_SET_SYSCALL_USER_DISPATCH.2const.gz

NAME

       PR_SET_SYSCALL_USER_DISPATCH - set the system-call user dispatch mechanism for the calling thread

LIBRARY

       Standard C library (libc, -lc)

SYNOPSIS

       #include <linux/prctl.h>  /* Definition of PR_* constants */
       #include <sys/prctl.h>

       int prctl(PR_SET_SYSCALL_USER_DISPATCH, long op, ...);

       int prctl(PR_SET_SYSCALL_USER_DISPATCH, PR_SYS_DISPATCH_ON,
                 unsigned long off, unsigned long size, int8_t *switch);
       int prctl(PR_SET_SYSCALL_USER_DISPATCH, PR_SYS_DISPATCH_OFF, 0L, 0L, 0L);

DESCRIPTION

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 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.

PR_SYS_DISPATCH_ON
Enable this mechanism.

Once enabled, further system calls will be selectively intercepted, depending on a control
variable provided by user space. In this case, off and size respectively identify the offset and
size of a single contiguous memory region in the process address space from where system calls are
always allowed to be executed, regardless of the control variable. (Typically, this area would
include the area of memory containing the C library.)

switch points to a variable that is a fast switch to allow/block system call execution without the
overhead of doing another system call to re-configure Syscall User Dispatch. This control
variable can either be set to SYSCALL_DISPATCH_FILTER_BLOCK to block system calls from executing
or to SYSCALL_DISPATCH_FILTER_ALLOW to temporarily allow them to be executed. This value is
checked by the kernel on every system call entry, and any unexpected value will raise an
uncatchable SIGSYS at that time, killing the application.

When a system call is intercepted, the kernel sends a thread-directed SIGSYS signal to the
triggering thread. Various fields will be set in the siginfo_t structure (see sigaction(2))
associated with the signal:

• si_signo will contain SIGSYS.

• si_call_addr will show the address of the system call instruction.

• si_syscall and si_arch will indicate which system call was attempted.

• si_code will contain SYS_USER_DISPATCH.

• si_errno will be set to 0.

The program counter will be as though the system call happened (i.e., the program counter will not
point to the system call instruction).

When the signal handler returns to the kernel, the system call completes immediately and returns
to the calling thread, without actually being executed. If necessary (i.e., when emulating the
system call on user space.), the signal handler should set the system call return value to a sane
value, by modifying the register context stored in the ucontext argument of the signal handler.
See sigaction(2), sigreturn(2), and getcontext(3) for more information.

PR_SYS_DISPATCH_OFF
Syscall User Dispatch is disabled for that thread.

The setting is not preserved across fork(2), clone(2), or execve(2).

RETURN VALUE

       On success, 0 is returned.  On error, -1 is returned, and errno is set to indicate the error.

ERRORS

       EFAULT switch is an invalid address.

       EINVAL op is PR_SYS_DISPATCH_ON and the memory range specified  is  outside  the  address  space  of  the
              process.

       EINVAL op is invalid.

STANDARDS

       Linux.  x86 only.

HISTORY

       Linux 5.11 (x86).