# PR_SET_SYSCALL_USER_DISPATCH

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


* * *