]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 2003 Free Software Foundation, Inc. |
14620a25 | 2 | .\" Copyright (C) 2015 Andrew Lutomirski |
86d38ba3 | 3 | .\" Author: Kent Yoder |
2297bf0e | 4 | .\" |
95fb8859 | 5 | .\" SPDX-License-Identifier: GPL-1.0-or-later |
fea681da | 6 | .\" |
4c1c5274 | 7 | .TH set_thread_area 2 (date) "Linux man-pages (unreleased)" |
fea681da | 8 | .SH NAME |
f7c3bc5c | 9 | get_thread_area, set_thread_area \- manipulate thread-local storage information |
25f0a22d AC |
10 | .SH LIBRARY |
11 | Standard C library | |
8fc3b2cf | 12 | .RI ( libc ", " \-lc ) |
47297adb | 13 | .SH SYNOPSIS |
52078966 | 14 | .nf |
ba4d34a1 AC |
15 | .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
16 | .B #include <unistd.h> | |
eaa18d3c | 17 | .PP |
f7c3bc5c | 18 | .B #if defined __i386__ || defined __x86_64__ |
ba4d34a1 | 19 | .BR "# include <asm/ldt.h>" " /* Definition of " "struct user_desc" " */" |
dbfe9c70 | 20 | .PP |
ba4d34a1 AC |
21 | .BI "int syscall(SYS_get_thread_area, struct user_desc *" u_info ); |
22 | .BI "int syscall(SYS_set_thread_area, struct user_desc *" u_info ); | |
f7c3bc5c ES |
23 | .PP |
24 | .B #elif defined __m68k__ | |
25 | .PP | |
ba4d34a1 AC |
26 | .B "int syscall(SYS_get_thread_area);" |
27 | .BI "int syscall(SYS_set_thread_area, unsigned long " tp ); | |
f7c3bc5c ES |
28 | .PP |
29 | .B #elif defined __mips__ | |
30 | .PP | |
ba4d34a1 | 31 | .BI "int syscall(SYS_set_thread_area, unsigned long " addr ); |
f7c3bc5c ES |
32 | .PP |
33 | .B #endif | |
52078966 | 34 | .fi |
dbfe9c70 | 35 | .PP |
52078966 | 36 | .IR Note : |
ba4d34a1 AC |
37 | glibc provides no wrappers for these system calls, |
38 | necessitating the use of | |
39 | .BR syscall (2). | |
52078966 | 40 | .SH DESCRIPTION |
f7c3bc5c ES |
41 | These calls provide architecture-specific support for a thread-local storage |
42 | implementation. | |
43 | At the moment, | |
44 | .BR set_thread_area () | |
45 | is available on m68k, MIPS, and x86 (both 32-bit and 64-bit variants); | |
46 | .BR get_thread_area () | |
47 | is available on m68k and x86. | |
48 | .PP | |
49 | On m68k and MIPS, | |
50 | .BR set_thread_area () | |
51 | allows storing an arbitrary pointer (provided in the | |
52 | .B tp | |
53 | argument on m68k and in the | |
54 | .B addr | |
e7871dad MK |
55 | argument on MIPS) |
56 | in the kernel data structure associated with the calling thread; | |
57 | this pointer can later be retrieved using | |
f7c3bc5c | 58 | .BR get_thread_area () |
e7871dad MK |
59 | (see also NOTES |
60 | for information regarding obtaining the thread pointer on MIPS). | |
f7c3bc5c ES |
61 | .PP |
62 | On x86, Linux dedicates three global descriptor table (GDT) entries for | |
52078966 MK |
63 | thread-local storage. |
64 | For more information about the GDT, see the | |
65 | Intel Software Developer's Manual or the AMD Architecture Programming Manual. | |
efeece04 | 66 | .PP |
52078966 MK |
67 | Both of these system calls take an argument that is a pointer |
68 | to a structure of the following type: | |
efeece04 | 69 | .PP |
52078966 | 70 | .in +4n |
b8302363 | 71 | .EX |
14620a25 AL |
72 | struct user_desc { |
73 | unsigned int entry_number; | |
59b191dc | 74 | unsigned int base_addr; |
14620a25 AL |
75 | unsigned int limit; |
76 | unsigned int seg_32bit:1; | |
77 | unsigned int contents:2; | |
78 | unsigned int read_exec_only:1; | |
79 | unsigned int limit_in_pages:1; | |
80 | unsigned int seg_not_present:1; | |
81 | unsigned int useable:1; | |
f7c3bc5c ES |
82 | #ifdef __x86_64__ |
83 | unsigned int lm:1; | |
84 | #endif | |
14620a25 | 85 | }; |
b8302363 | 86 | .EE |
e646a1ba | 87 | .in |
efeece04 | 88 | .PP |
14620a25 AL |
89 | .BR get_thread_area () |
90 | reads the GDT entry indicated by | |
91 | .I u_info\->entry_number | |
92 | and fills in the rest of the fields in | |
52078966 | 93 | .IR u_info . |
efeece04 | 94 | .PP |
e511ffb6 | 95 | .BR set_thread_area () |
14620a25 AL |
96 | sets a TLS entry in the GDT. |
97 | .PP | |
fea681da | 98 | The TLS array entry set by |
e511ffb6 | 99 | .BR set_thread_area () |
fea681da | 100 | corresponds to the value of |
94e9d9fe | 101 | .I u_info\->entry_number |
c13182ef MK |
102 | passed in by the user. |
103 | If this value is in bounds, | |
e511ffb6 | 104 | .BR set_thread_area () |
14620a25 | 105 | writes the TLS descriptor pointed to by |
fea681da MK |
106 | .I u_info |
107 | into the thread's TLS array. | |
108 | .PP | |
109 | When | |
e511ffb6 | 110 | .BR set_thread_area () |
fea681da MK |
111 | is passed an |
112 | .I entry_number | |
ed26cc5a | 113 | of \-1, it searches for a free TLS entry. |
c13182ef | 114 | If |
e511ffb6 | 115 | .BR set_thread_area () |
c13182ef | 116 | finds a free TLS entry, the value of |
94e9d9fe | 117 | .I u_info\->entry_number |
fea681da | 118 | is set upon return to show which entry was changed. |
14620a25 AL |
119 | .PP |
120 | A | |
121 | .I user_desc | |
122 | is considered "empty" if | |
123 | .I read_exec_only | |
124 | and | |
125 | .I seg_not_present | |
52078966 MK |
126 | are set to 1 and all of the other fields are 0. |
127 | If an "empty" descriptor is passed to | |
91e37771 | 128 | .BR set_thread_area (), |
52078966 MK |
129 | the corresponding TLS entry will be cleared. |
130 | See BUGS for additional details. | |
14620a25 | 131 | .PP |
52078966 | 132 | Since Linux 3.19, |
14620a25 AL |
133 | .BR set_thread_area () |
134 | cannot be used to write non-present segments, 16-bit segments, or code | |
135 | segments, although clearing a segment is still acceptable. | |
47297adb | 136 | .SH RETURN VALUE |
e7871dad | 137 | On x86, these system calls |
52078966 | 138 | return 0 on success, and \-1 on failure, with |
fea681da | 139 | .I errno |
f6a4078b | 140 | set to indicate the error. |
f7c3bc5c ES |
141 | .PP |
142 | On MIPS and m68k, | |
143 | .BR set_thread_area () | |
e7871dad | 144 | always returns 0. |
f7c3bc5c ES |
145 | On m68k, |
146 | .BR get_thread_area () | |
e7871dad MK |
147 | returns the thread area pointer value |
148 | (previously set via | |
149 | .BR set_thread_area ()). | |
47297adb | 150 | .SH ERRORS |
fea681da | 151 | .TP |
fea681da | 152 | .B EFAULT |
a8d55537 | 153 | \fIu_info\fP is an invalid pointer. |
fea681da | 154 | .TP |
52078966 MK |
155 | .B EINVAL |
156 | \fIu_info\->entry_number\fP is out of bounds. | |
157 | .TP | |
14620a25 | 158 | .B ENOSYS |
bf7bc8b8 | 159 | .BR get_thread_area () |
14620a25 | 160 | or |
bf7bc8b8 | 161 | .BR set_thread_area () |
52078966 MK |
162 | was invoked as a 64-bit system call. |
163 | .TP | |
164 | .B ESRCH | |
165 | .RB ( set_thread_area ()) | |
166 | A free TLS entry could not be located. | |
47297adb | 167 | .SH VERSIONS |
e511ffb6 | 168 | .BR set_thread_area () |
fea681da | 169 | first appeared in Linux 2.5.29. |
52078966 MK |
170 | .BR get_thread_area () |
171 | first appeared in Linux 2.5.32. | |
3113c7f3 | 172 | .SH STANDARDS |
b30b425b MK |
173 | .BR set_thread_area () |
174 | and | |
175 | .BR get_thread_area () | |
49ea23a1 | 176 | are Linux-specific and should not be used in programs that are intended |
a1d5f77c | 177 | to be portable. |
52078966 | 178 | .SH NOTES |
ba4d34a1 | 179 | These system calls are generally intended for use only by threading libraries. |
52078966 MK |
180 | .PP |
181 | .BR arch_prctl (2) | |
182 | can interfere with | |
f7c3bc5c ES |
183 | .BR set_thread_area () |
184 | on x86. | |
52078966 MK |
185 | See |
186 | .BR arch_prctl (2) | |
187 | for more details. | |
188 | This is not normally a problem, as | |
189 | .BR arch_prctl (2) | |
190 | is normally used only by 64-bit programs. | |
f7c3bc5c | 191 | .PP |
e7871dad MK |
192 | On MIPS, the current value of the thread area pointer can be obtained |
193 | using the instruction: | |
194 | .PP | |
195 | .in +4n | |
196 | .EX | |
197 | rdhwr dest, $29 | |
198 | .EE | |
199 | .in | |
200 | .PP | |
201 | This instruction traps and is handled by kernel. | |
14620a25 | 202 | .SH BUGS |
ed26cc5a MK |
203 | On 64-bit kernels before Linux 3.19, |
204 | .\" commit e30ab185c490e9a9381385529e0fd32f0a399495 | |
205 | one of the padding bits in | |
52078966 | 206 | .IR user_desc , |
ed26cc5a MK |
207 | if set, would prevent the descriptor from being considered empty (see |
208 | .BR modify_ldt (2)). | |
14620a25 | 209 | As a result, the only reliable way to clear a TLS entry is to use |
52078966 MK |
210 | .BR memset (3) |
211 | to zero the entire | |
14620a25 AL |
212 | .I user_desc |
213 | structure, including padding bits, and then to set the | |
214 | .I read_exec_only | |
215 | and | |
216 | .I seg_not_present | |
52078966 MK |
217 | bits. |
218 | On Linux 3.19, a | |
14620a25 AL |
219 | .I user_desc |
220 | consisting entirely of zeros except for | |
221 | .I entry_number | |
222 | will also be interpreted as a request to clear a TLS entry, but this | |
223 | behaved differently on older kernels. | |
224 | .PP | |
225 | Prior to Linux 3.19, the DS and ES segment registers must not reference | |
226 | TLS entries. | |
47297adb | 227 | .SH SEE ALSO |
14620a25 | 228 | .BR arch_prctl (2), |
01fc1d84 | 229 | .BR modify_ldt (2), |
c9a1d477 MK |
230 | .BR ptrace (2) |
231 | .RB ( PTRACE_GET_THREAD_AREA " and " PTRACE_SET_THREAD_AREA ) |