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