arch_prctl(2)

1arch_prctl(2)                 System Calls Manual                arch_prctl(2)
2
3
4

NAME

6       arch_prctl - set architecture-specific thread state
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <asm/prctl.h>        /* Definition of ARCH_* constants */
13       #include <sys/syscall.h>      /* Definition of SYS_* constants */
14       #include <unistd.h>
15
16       int syscall(SYS_arch_prctl, int code, unsigned long addr);
17       int syscall(SYS_arch_prctl, int code, unsigned long *addr);
18
19       Note: glibc provides no wrapper for arch_prctl(), necessitating the use
20       of syscall(2).
21

DESCRIPTION

23       arch_prctl() sets architecture-specific process or thread state.   code
24       selects  a  subfunction  and passes argument addr to it; addr is inter‐
25       preted as either an unsigned long for the "set" operations,  or  as  an
26       unsigned long *, for the "get" operations.
27
28       Subfunctions for both x86 and x86-64 are:
29
30       ARCH_SET_CPUID (since Linux 4.12)
31              Enable  (addr != 0) or disable (addr == 0) the cpuid instruction
32              for the calling thread.  The instruction is enabled by  default.
33              If  disabled,  any execution of a cpuid instruction will instead
34              generate a SIGSEGV signal.  This feature can be used to  emulate
35              cpuid  results  that  differ  from  what the underlying hardware
36              would have produced (e.g., in a paravirtualization setting).
37
38              The ARCH_SET_CPUID  setting  is  preserved  across  fork(2)  and
39              clone(2)  but  reset to the default (i.e., cpuid enabled) on ex‐
40              ecve(2).
41
42       ARCH_GET_CPUID (since Linux 4.12)
43              Return the setting of the flag manipulated by ARCH_SET_CPUID  as
44              the  result  of the system call (1 for enabled, 0 for disabled).
45              addr is ignored.
46
47       Subfunctions for x86-64 only are:
48
49       ARCH_SET_FS
50              Set the 64-bit base for the FS register to addr.
51
52       ARCH_GET_FS
53              Return the 64-bit base value for the FS register of the  calling
54              thread in the unsigned long pointed to by addr.
55
56       ARCH_SET_GS
57              Set the 64-bit base for the GS register to addr.
58
59       ARCH_GET_GS
60              Return  the 64-bit base value for the GS register of the calling
61              thread in the unsigned long pointed to by addr.
62

RETURN VALUE

64       On success, arch_prctl() returns 0; on error, -1 is returned, and errno
65       is set to indicate the error.
66

ERRORS

68       EFAULT addr points to an unmapped address or is outside the process ad‐
69              dress space.
70
71       EINVAL code is not a valid subcommand.
72
73       ENODEV ARCH_SET_CPUID was requested, but the underlying  hardware  does
74              not support CPUID faulting.
75
76       EPERM  addr is outside the process address space.
77

STANDARDS

79       Linux/x86-64.
80

NOTES

82       arch_prctl() is supported only on Linux/x86-64 for 64-bit programs cur‐
83       rently.
84
85       The 64-bit base changes when a new 32-bit segment selector is loaded.
86
87       ARCH_SET_GS is disabled in some kernels.
88
89       Context switches for 64-bit segment bases are rather expensive.  As  an
90       optimization,  if  a  32-bit TLS base address is used, arch_prctl() may
91       use a real TLS entry as if set_thread_area(2) had been called,  instead
92       of  manipulating  the  segment  base  register directly.  Memory in the
93       first 2 GB of address space can be allocated by using mmap(2) with  the
94       MAP_32BIT flag.
95
96       Because  of  the  aforementioned  optimization,  using arch_prctl() and
97       set_thread_area(2) in the same thread is dangerous, as they  may  over‐
98       write each other's TLS entries.
99
100       FS  may  be  already  used by the threading library.  Programs that use
101       ARCH_SET_FS directly are very likely to crash.
102