1 .\" Copyright (C) 2003 Free Software Foundation, Inc.
2 .\" Copyright (C) 2015 Andrew Lutomirski
5 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
6 .\" This file is distributed according to the GNU General Public License.
9 .TH SET_THREAD_AREA 2 2021-03-22 "Linux" "Linux Programmer's Manual"
11 get_thread_area, set_thread_area \- manipulate thread-local storage information
14 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
15 .B #include <unistd.h>
17 .B #if defined __i386__ || defined __x86_64__
18 .BR "# include <asm/ldt.h>" " /* Definition of " "struct user_desc" " */"
20 .BI "int syscall(SYS_get_thread_area, struct user_desc *" u_info );
21 .BI "int syscall(SYS_set_thread_area, struct user_desc *" u_info );
23 .B #elif defined __m68k__
25 .B "int syscall(SYS_get_thread_area);"
26 .BI "int syscall(SYS_set_thread_area, unsigned long " tp );
28 .B #elif defined __mips__
30 .BI "int syscall(SYS_set_thread_area, unsigned long " addr );
36 glibc provides no wrappers for these system calls,
37 necessitating the use of
40 These calls provide architecture-specific support for a thread-local storage
43 .BR set_thread_area ()
44 is available on m68k, MIPS, and x86 (both 32-bit and 64-bit variants);
45 .BR get_thread_area ()
46 is available on m68k and x86.
49 .BR set_thread_area ()
50 allows storing an arbitrary pointer (provided in the
52 argument on m68k and in the
55 in the kernel data structure associated with the calling thread;
56 this pointer can later be retrieved using
57 .BR get_thread_area ()
59 for information regarding obtaining the thread pointer on MIPS).
61 On x86, Linux dedicates three global descriptor table (GDT) entries for
63 For more information about the GDT, see the
64 Intel Software Developer's Manual or the AMD Architecture Programming Manual.
66 Both of these system calls take an argument that is a pointer
67 to a structure of the following type:
72 unsigned int entry_number;
73 unsigned int base_addr;
75 unsigned int seg_32bit:1;
76 unsigned int contents:2;
77 unsigned int read_exec_only:1;
78 unsigned int limit_in_pages:1;
79 unsigned int seg_not_present:1;
80 unsigned int useable:1;
88 .BR get_thread_area ()
89 reads the GDT entry indicated by
90 .I u_info\->entry_number
91 and fills in the rest of the fields in
94 .BR set_thread_area ()
95 sets a TLS entry in the GDT.
97 The TLS array entry set by
98 .BR set_thread_area ()
99 corresponds to the value of
100 .I u_info\->entry_number
101 passed in by the user.
102 If this value is in bounds,
103 .BR set_thread_area ()
104 writes the TLS descriptor pointed to by
106 into the thread's TLS array.
109 .BR set_thread_area ()
112 of \-1, it searches for a free TLS entry.
114 .BR set_thread_area ()
115 finds a free TLS entry, the value of
116 .I u_info\->entry_number
117 is set upon return to show which entry was changed.
121 is considered "empty" if
125 are set to 1 and all of the other fields are 0.
126 If an "empty" descriptor is passed to
127 .BR set_thread_area (),
128 the corresponding TLS entry will be cleared.
129 See BUGS for additional details.
132 .BR set_thread_area ()
133 cannot be used to write non-present segments, 16-bit segments, or code
134 segments, although clearing a segment is still acceptable.
136 On x86, these system calls
137 return 0 on success, and \-1 on failure, with
139 set to indicate the error.
142 .BR set_thread_area ()
145 .BR get_thread_area ()
146 returns the thread area pointer value
148 .BR set_thread_area ()).
152 \fIu_info\fP is an invalid pointer.
155 \fIu_info\->entry_number\fP is out of bounds.
158 .BR get_thread_area ()
160 .BR set_thread_area ()
161 was invoked as a 64-bit system call.
164 .RB ( set_thread_area ())
165 A free TLS entry could not be located.
167 .BR set_thread_area ()
168 first appeared in Linux 2.5.29.
169 .BR get_thread_area ()
170 first appeared in Linux 2.5.32.
172 .BR set_thread_area ()
174 .BR get_thread_area ()
175 are Linux-specific and should not be used in programs that are intended
178 These system calls are generally intended for use only by threading libraries.
182 .BR set_thread_area ()
187 This is not normally a problem, as
189 is normally used only by 64-bit programs.
191 On MIPS, the current value of the thread area pointer can be obtained
192 using the instruction:
200 This instruction traps and is handled by kernel.
202 On 64-bit kernels before Linux 3.19,
203 .\" commit e30ab185c490e9a9381385529e0fd32f0a399495
204 one of the padding bits in
206 if set, would prevent the descriptor from being considered empty (see
208 As a result, the only reliable way to clear a TLS entry is to use
212 structure, including padding bits, and then to set the
219 consisting entirely of zeros except for
221 will also be interpreted as a request to clear a TLS entry, but this
222 behaved differently on older kernels.
224 Prior to Linux 3.19, the DS and ES segment registers must not reference
230 .RB ( PTRACE_GET_THREAD_AREA " and " PTRACE_SET_THREAD_AREA )