man2/arch_prctl.2

   1 .\" Copyright (C) 2003 Andi Kleen
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH ARCH_PRCTL 2 2021-08-27 "Linux" "Linux Programmer's Manual"
   6 .SH NAME
   7 arch_prctl \- set architecture-specific thread state
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .BR "#include <asm/prctl.h>" "        /* Definition of " ARCH_* " constants */"
  14 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  15 .B #include <unistd.h>
  16 .PP
  17 .BI "int syscall(SYS_arch_prctl, int " code ", unsigned long " addr );
  18 .BI "int syscall(SYS_arch_prctl, int " code ", unsigned long *" addr );
  19 .fi
  20 .PP
  21 .IR Note :
  22 glibc provides no wrapper for
  23 .BR arch_prctl (),
  24 necessitating the use of
  25 .BR syscall (2).
  26 .SH DESCRIPTION
  27 .BR arch_prctl ()
  28 sets architecture-specific process or thread state.
  29 .I code
  30 selects a subfunction
  31 and passes argument
  32 .I addr
  33 to it;
  34 .I addr
  35 is interpreted as either an
  36 .I "unsigned long"
  37 for the "set" operations, or as an
  38 .IR "unsigned long\ *" ,
  39 for the "get" operations.
  40 .PP
  41 Subfunctions for both x86 and x86-64 are:
  42 .TP
  43 .BR ARCH_SET_CPUID " (since Linux 4.12)"
  44 .\" commit e9ea1e7f53b852147cbd568b0568c7ad97ec21a3
  45 Enable
  46 .RI ( "addr != 0" )
  47 or disable
  48 .RI ( "addr == 0" )
  49 the
  50 .I cpuid
  51 instruction for the calling thread.
  52 The instruction is enabled by default.
  53 If disabled, any execution of a
  54 .I cpuid
  55 instruction will instead generate a
  56 .B SIGSEGV
  57 signal.
  58 This feature can be used to emulate
  59 .I cpuid
  60 results that differ from what the underlying
  61 hardware would have produced (e.g., in a paravirtualization setting).
  62 .IP
  63 The
  64 .B ARCH_SET_CPUID
  65 setting is preserved across
  66 .BR fork (2)
  67 and
  68 .BR clone (2)
  69 but reset to the default (i.e.,
  70 .I cpuid
  71 enabled) on
  72 .BR execve (2).
  73 .TP
  74 .BR ARCH_GET_CPUID " (since Linux 4.12)"
  75 Return the setting of the flag manipulated by
  76 .B ARCH_SET_CPUID
  77 as the result of the system call (1 for enabled, 0 for disabled).
  78 .I addr
  79 is ignored.
  80 .TP
  81 Subfunctions for x86-64 only are:
  82 .TP
  83 .B ARCH_SET_FS
  84 Set the 64-bit base for the
  85 .I FS
  86 register to
  87 .IR addr .
  88 .TP
  89 .B ARCH_GET_FS
  90 Return the 64-bit base value for the
  91 .I FS
  92 register of the calling thread in the
  93 .I unsigned long
  94 pointed to by
  95 .IR addr .
  96 .TP
  97 .B ARCH_SET_GS
  98 Set the 64-bit base for the
  99 .I GS
 100 register to
 101 .IR addr .
 102 .TP
 103 .B ARCH_GET_GS
 104 Return the 64-bit base value for the
 105 .I GS
 106 register of the calling thread in the
 107 .I unsigned long
 108 pointed to by
 109 .IR addr .
 110 .SH RETURN VALUE
 111 On success,
 112 .BR arch_prctl ()
 113 returns 0; on error, \-1 is returned, and
 114 .I errno
 115 is set to indicate the error.
 116 .SH ERRORS
 117 .TP
 118 .B EFAULT
 119 .I addr
 120 points to an unmapped address or is outside the process address space.
 121 .TP
 122 .B EINVAL
 123 .I code
 124 is not a valid subcommand.
 125 .TP
 126 .B ENODEV
 127 .B ARCH_SET_CPUID
 128 was requested, but the underlying hardware does not support CPUID faulting.
 129 .TP
 130 .B EPERM
 131 .I addr
 132 is outside the process address space.
 133 .\" .SH AUTHOR
 134 .\" Man page written by Andi Kleen.
 135 .SH STANDARDS
 136 .BR arch_prctl ()
 137 is a Linux/x86-64 extension and should not be used in programs intended
 138 to be portable.
 139 .SH NOTES
 140 .BR arch_prctl ()
 141 is supported only on Linux/x86-64 for 64-bit programs currently.
 142 .PP
 143 The 64-bit base changes when a new 32-bit segment selector is loaded.
 144 .PP
 145 .B ARCH_SET_GS
 146 is disabled in some kernels.
 147 .PP
 148 Context switches for 64-bit segment bases are rather expensive.
 149 As an optimization, if a 32-bit TLS base address is used,
 150 .BR arch_prctl ()
 151 may use a real TLS entry as if
 152 .BR set_thread_area (2)
 153 had been called, instead of manipulating the segment base register directly.
 154 Memory in the first 2\ GB of address space can be allocated by using
 155 .BR mmap (2)
 156 with the
 157 .B MAP_32BIT
 158 flag.
 159 .PP
 160 Because of the aforementioned optimization, using
 161 .BR arch_prctl ()
 162 and
 163 .BR set_thread_area (2)
 164 in the same thread is dangerous, as they may overwrite each other's
 165 TLS entries.
 166 .PP
 167 .I FS
 168 may be already used by the threading library.
 169 Programs that use
 170 .B ARCH_SET_FS
 171 directly are very likely to crash.
 172 .SH SEE ALSO
 173 .BR mmap (2),
 174 .BR modify_ldt (2),
 175 .BR prctl (2),
 176 .BR set_thread_area (2)
 177 .PP
 178 AMD X86-64 Programmer's manual