Debian Codegraph @

upstream/debian-unstable/man2/arch_prctl.2

raw
1 .\" Copyright 2003, Andi Kleen <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH arch_prctl 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 arch_prctl \- set architecture-specific thread state
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <asm/prctl.h>" " /* Definition of " ARCH_* " constants */"
15 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
16 .B #include <unistd.h>
17 .P
18 .BI "int syscall(SYS_arch_prctl, int " op ", unsigned long " addr );
19 .BI "int syscall(SYS_arch_prctl, int " op ", unsigned long *" addr );
20 .fi
21 .P
22 .IR Note :
23 glibc provides no wrapper for
24 .BR arch_prctl (),
25 necessitating the use of
26 .BR syscall (2).
27 .SH DESCRIPTION
28 .BR arch_prctl ()
29 sets architecture-specific process or thread state.
30 .I op
31 selects an operation
32 and passes argument
33 .I addr
34 to it;
35 .I addr
36 is interpreted as either an
37 .I "unsigned long"
38 for the "set" operations, or as an
39 .IR "unsigned long\ *" ,
40 for the "get" operations.
41 .P
42 Subfunctions for both x86 and x86-64 are:
43 .TP
44 .BR ARCH_SET_CPUID " (since Linux 4.12)"
45 .\" commit e9ea1e7f53b852147cbd568b0568c7ad97ec21a3
46 Enable
47 .RI ( "addr != 0" )
48 or disable
49 .RI ( "addr == 0" )
50 the
51 .I cpuid
52 instruction for the calling thread.
53 The instruction is enabled by default.
54 If disabled, any execution of a
55 .I cpuid
56 instruction will instead generate a
57 .B SIGSEGV
58 signal.
59 This feature can be used to emulate
60 .I cpuid
61 results that differ from what the underlying
62 hardware would have produced (e.g., in a paravirtualization setting).
63 .IP
64 The
65 .B ARCH_SET_CPUID
66 setting is preserved across
67 .BR fork (2)
68 and
69 .BR clone (2)
70 but reset to the default (i.e.,
71 .I cpuid
72 enabled) on
73 .BR execve (2).
74 .TP
75 .BR ARCH_GET_CPUID " (since Linux 4.12)"
76 Return the setting of the flag manipulated by
77 .B ARCH_SET_CPUID
78 as the result of the system call (1 for enabled, 0 for disabled).
79 .I addr
80 is ignored.
81 .TP
82 Subfunctions for x86-64 only are:
83 .TP
84 .B ARCH_SET_FS
85 Set the 64-bit base for the
86 .I FS
87 register to
88 .IR addr .
89 .TP
90 .B ARCH_GET_FS
91 Return the 64-bit base value for the
92 .I FS
93 register of the calling thread in the
94 .I unsigned long
95 pointed to by
96 .IR addr .
97 .TP
98 .B ARCH_SET_GS
99 Set the 64-bit base for the
100 .I GS
101 register to
102 .IR addr .
103 .TP
104 .B ARCH_GET_GS
105 Return the 64-bit base value for the
106 .I GS
107 register of the calling thread in the
108 .I unsigned long
109 pointed to by
110 .IR addr .
111 .SH RETURN VALUE
112 On success,
113 .BR arch_prctl ()
114 returns 0;
115 on error, \-1 is returned, and
116 .I errno
117 is set to indicate the error.
118 .SH ERRORS
119 .TP
120 .B EFAULT
121 .I addr
122 points to an unmapped address or is outside the process address space.
123 .TP
124 .B EINVAL
125 .I op
126 is not a valid operation.
127 .TP
128 .B ENODEV
129 .B ARCH_SET_CPUID
130 was requested, but the underlying hardware does not support CPUID faulting.
131 .TP
132 .B EPERM
133 .I addr
134 is outside the process address space.
135 .\" .SH AUTHOR
136 .\" Man page written by Andi Kleen.
137 .SH STANDARDS
138 Linux/x86-64.
139 .SH NOTES
140 .BR arch_prctl ()
141 is supported only on Linux/x86-64 for 64-bit programs currently.
142 .P
143 The 64-bit base changes when a new 32-bit segment selector is loaded.
144 .P
145 .B ARCH_SET_GS
146 is disabled in some kernels.
147 .P
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 .P
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 .P
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 .P
178 AMD X86-64 Programmer's manual