| 1 |
.\" Copyright 2003, Free Software Foundation, Inc. |
| 2 |
.\" Copyright 2015, Andrew Lutomirski <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: GPL-1.0-or-later |
| 6 |
.\" |
| 7 |
.TH set_thread_area 2 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
get_thread_area, set_thread_area \- manipulate thread-local storage information |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
| 16 |
.B #include <unistd.h> |
| 17 |
.P |
| 18 |
.B #if defined __i386__ || defined __x86_64__ |
| 19 |
.BR "# include <asm/ldt.h>" " /* Definition of " "struct user_desc" " */" |
| 20 |
.P |
| 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 ); |
| 23 |
.P |
| 24 |
.B #elif defined __m68k__ |
| 25 |
.P |
| 26 |
.B "int syscall(SYS_get_thread_area);" |
| 27 |
.BI "int syscall(SYS_set_thread_area, unsigned long " tp ); |
| 28 |
.P |
| 29 |
.B #elif defined __mips__ || defined __csky__ |
| 30 |
.P |
| 31 |
.BI "int syscall(SYS_set_thread_area, unsigned long " addr ); |
| 32 |
.P |
| 33 |
.B #endif |
| 34 |
.fi |
| 35 |
.P |
| 36 |
.IR Note : |
| 37 |
glibc provides no wrappers for these system calls, |
| 38 |
necessitating the use of |
| 39 |
.BR syscall (2). |
| 40 |
.SH DESCRIPTION |
| 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, C-SKY, and x86 (both 32-bit and 64-bit variants); |
| 46 |
.BR get_thread_area () |
| 47 |
is available on m68k and x86. |
| 48 |
.P |
| 49 |
On m68k, MIPS and C-SKY, |
| 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 |
| 55 |
argument on MIPS and C-SKY) |
| 56 |
in the kernel data structure associated with the calling thread; |
| 57 |
this pointer can later be retrieved using |
| 58 |
.BR get_thread_area () |
| 59 |
(see also NOTES |
| 60 |
for information regarding obtaining the thread pointer on MIPS). |
| 61 |
.P |
| 62 |
On x86, Linux dedicates three global descriptor table (GDT) entries for |
| 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. |
| 66 |
.P |
| 67 |
Both of these system calls take an argument that is a pointer |
| 68 |
to a structure of the following type: |
| 69 |
.P |
| 70 |
.in +4n |
| 71 |
.EX |
| 72 |
struct user_desc { |
| 73 |
unsigned int entry_number; |
| 74 |
unsigned int base_addr; |
| 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; |
| 82 |
#ifdef __x86_64__ |
| 83 |
unsigned int lm:1; |
| 84 |
#endif |
| 85 |
}; |
| 86 |
.EE |
| 87 |
.in |
| 88 |
.P |
| 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 |
| 93 |
.IR u_info . |
| 94 |
.P |
| 95 |
.BR set_thread_area () |
| 96 |
sets a TLS entry in the GDT. |
| 97 |
.P |
| 98 |
The TLS array entry set by |
| 99 |
.BR set_thread_area () |
| 100 |
corresponds to the value of |
| 101 |
.I u_info\->entry_number |
| 102 |
passed in by the user. |
| 103 |
If this value is in bounds, |
| 104 |
.BR set_thread_area () |
| 105 |
writes the TLS descriptor pointed to by |
| 106 |
.I u_info |
| 107 |
into the thread's TLS array. |
| 108 |
.P |
| 109 |
When |
| 110 |
.BR set_thread_area () |
| 111 |
is passed an |
| 112 |
.I entry_number |
| 113 |
of \-1, it searches for a free TLS entry. |
| 114 |
If |
| 115 |
.BR set_thread_area () |
| 116 |
finds a free TLS entry, the value of |
| 117 |
.I u_info\->entry_number |
| 118 |
is set upon return to show which entry was changed. |
| 119 |
.P |
| 120 |
A |
| 121 |
.I user_desc |
| 122 |
is considered "empty" if |
| 123 |
.I read_exec_only |
| 124 |
and |
| 125 |
.I seg_not_present |
| 126 |
are set to 1 and all of the other fields are 0. |
| 127 |
If an "empty" descriptor is passed to |
| 128 |
.BR set_thread_area (), |
| 129 |
the corresponding TLS entry will be cleared. |
| 130 |
See BUGS for additional details. |
| 131 |
.P |
| 132 |
Since Linux 3.19, |
| 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. |
| 136 |
.SH RETURN VALUE |
| 137 |
On x86, these system calls |
| 138 |
return 0 on success, and \-1 on failure, with |
| 139 |
.I errno |
| 140 |
set to indicate the error. |
| 141 |
.P |
| 142 |
On C-SKY, MIPS and m68k, |
| 143 |
.BR set_thread_area () |
| 144 |
always returns 0. |
| 145 |
On m68k, |
| 146 |
.BR get_thread_area () |
| 147 |
returns the thread area pointer value |
| 148 |
(previously set via |
| 149 |
.BR set_thread_area ()). |
| 150 |
.SH ERRORS |
| 151 |
.TP |
| 152 |
.B EFAULT |
| 153 |
.I u_info |
| 154 |
is an invalid pointer. |
| 155 |
.TP |
| 156 |
.B EINVAL |
| 157 |
.I u_info\->entry_number |
| 158 |
is out of bounds. |
| 159 |
.TP |
| 160 |
.B ENOSYS |
| 161 |
.BR get_thread_area () |
| 162 |
or |
| 163 |
.BR set_thread_area () |
| 164 |
was invoked as a 64-bit system call. |
| 165 |
.TP |
| 166 |
.B ESRCH |
| 167 |
.RB ( set_thread_area ()) |
| 168 |
A free TLS entry could not be located. |
| 169 |
.SH STANDARDS |
| 170 |
Linux. |
| 171 |
.SH HISTORY |
| 172 |
.TP |
| 173 |
.BR set_thread_area () |
| 174 |
Linux 2.5.29. |
| 175 |
.TP |
| 176 |
.BR get_thread_area () |
| 177 |
Linux 2.5.32. |
| 178 |
.SH NOTES |
| 179 |
These system calls are generally intended for use only by threading libraries. |
| 180 |
.P |
| 181 |
.BR arch_prctl (2) |
| 182 |
can interfere with |
| 183 |
.BR set_thread_area () |
| 184 |
on x86. |
| 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. |
| 191 |
.P |
| 192 |
On MIPS, the current value of the thread area pointer can be obtained |
| 193 |
using the instruction: |
| 194 |
.P |
| 195 |
.in +4n |
| 196 |
.EX |
| 197 |
rdhwr dest, $29 |
| 198 |
.EE |
| 199 |
.in |
| 200 |
.P |
| 201 |
This instruction traps and is handled by kernel. |
| 202 |
.SH BUGS |
| 203 |
On 64-bit kernels before Linux 3.19, |
| 204 |
.\" commit e30ab185c490e9a9381385529e0fd32f0a399495 |
| 205 |
one of the padding bits in |
| 206 |
.IR user_desc , |
| 207 |
if set, would prevent the descriptor from being considered empty (see |
| 208 |
.BR modify_ldt (2)). |
| 209 |
As a result, the only reliable way to clear a TLS entry is to use |
| 210 |
.BR memset (3) |
| 211 |
to zero the entire |
| 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 |
| 217 |
bits. |
| 218 |
On Linux 3.19, a |
| 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 |
.P |
| 225 |
Prior to Linux 3.19, the DS and ES segment registers must not reference |
| 226 |
TLS entries. |
| 227 |
.SH SEE ALSO |
| 228 |
.BR arch_prctl (2), |
| 229 |
.BR modify_ldt (2), |
| 230 |
.BR ptrace (2) |
| 231 |
.RB ( PTRACE_GET_THREAD_AREA " and " PTRACE_SET_THREAD_AREA ) |