Debian Codegraph @

upstream/debian-trixie/man2/arch_prctl.2

raw
1 .\" Copyright (C) 2003 Andi Kleen
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH arch_prctl 2 2024-05-02 "Linux man-pages 6.9.1"
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 .P
17 .BI "int syscall(SYS_arch_prctl, int " op ", unsigned long " addr );
18 .BI "int syscall(SYS_arch_prctl, int " op ", unsigned long *" addr );
19 .fi
20 .P
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 op
30 selects an operation
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 .P
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 op
124 is not a valid operation.
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 Linux/x86-64.
137 .SH NOTES
138 .BR arch_prctl ()
139 is supported only on Linux/x86-64 for 64-bit programs currently.
140 .P
141 The 64-bit base changes when a new 32-bit segment selector is loaded.
142 .P
143 .B ARCH_SET_GS
144 is disabled in some kernels.
145 .P
146 Context switches for 64-bit segment bases are rather expensive.
147 As an optimization, if a 32-bit TLS base address is used,
148 .BR arch_prctl ()
149 may use a real TLS entry as if
150 .BR set_thread_area (2)
151 had been called, instead of manipulating the segment base register directly.
152 Memory in the first 2\ GB of address space can be allocated by using
153 .BR mmap (2)
154 with the
155 .B MAP_32BIT
156 flag.
157 .P
158 Because of the aforementioned optimization, using
159 .BR arch_prctl ()
160 and
161 .BR set_thread_area (2)
162 in the same thread is dangerous, as they may overwrite each other's
163 TLS entries.
164 .P
165 .I FS
166 may be already used by the threading library.
167 Programs that use
168 .B ARCH_SET_FS
169 directly are very likely to crash.
170 .SH SEE ALSO
171 .BR mmap (2),
172 .BR modify_ldt (2),
173 .BR prctl (2),
174 .BR set_thread_area (2)
175 .P
176 AMD X86-64 Programmer's manual