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 2017-09-15 "Linux" "Linux Programmer's Manual"
11 get_thread_area, set_thread_area \- manipulate thread-local storage information
14 .B #include <linux/unistd.h>
16 .B #if defined __i386__ || defined __x86_64__
17 .B # include <asm/ldt.h>
19 .BI "int get_thread_area(struct user_desc *" u_info );
20 .BI "int set_thread_area(struct user_desc *" u_info );
22 .B #elif defined __m68k__
24 .B "int get_thread_area(void);
25 .BI "int set_thread_area(unsigned long " tp );
27 .B #elif defined __mips__
29 .BI "int set_thread_area(unsigned long " addr );
35 There are no glibc wrappers for these system calls; see NOTES.
37 These calls provide architecture-specific support for a thread-local storage
40 .BR set_thread_area ()
41 is available on m68k, MIPS, and x86 (both 32-bit and 64-bit variants);
42 .BR get_thread_area ()
43 is available on m68k and x86.
46 .BR set_thread_area ()
47 allows storing an arbitrary pointer (provided in the
49 argument on m68k and in the
52 in the kernel data structure associated with the calling thread;
53 this pointer can later be retrieved using
54 .BR get_thread_area ()
56 for information regarding obtaining the thread pointer on MIPS).
58 On x86, Linux dedicates three global descriptor table (GDT) entries for
60 For more information about the GDT, see the
61 Intel Software Developer's Manual or the AMD Architecture Programming Manual.
63 Both of these system calls take an argument that is a pointer
64 to a structure of the following type:
69 unsigned int entry_number;
70 unsigned long base_addr;
72 unsigned int seg_32bit:1;
73 unsigned int contents:2;
74 unsigned int read_exec_only:1;
75 unsigned int limit_in_pages:1;
76 unsigned int seg_not_present:1;
77 unsigned int useable:1;
85 .BR get_thread_area ()
86 reads the GDT entry indicated by
87 .I u_info\->entry_number
88 and fills in the rest of the fields in
91 .BR set_thread_area ()
92 sets a TLS entry in the GDT.
94 The TLS array entry set by
95 .BR set_thread_area ()
96 corresponds to the value of
97 .I u_info\->entry_number
98 passed in by the user.
99 If this value is in bounds,
100 .BR set_thread_area ()
101 writes the TLS descriptor pointed to by
103 into the thread's TLS array.
106 .BR set_thread_area ()
109 of \-1, it searches for a free TLS entry.
111 .BR set_thread_area ()
112 finds a free TLS entry, the value of
113 .I u_info\->entry_number
114 is set upon return to show which entry was changed.
118 is considered "empty" if
122 are set to 1 and all of the other fields are 0.
123 If an "empty" descriptor is passed to
125 the corresponding TLS entry will be cleared.
126 See BUGS for additional details.
129 .BR set_thread_area ()
130 cannot be used to write non-present segments, 16-bit segments, or code
131 segments, although clearing a segment is still acceptable.
133 On x86, these system calls
134 return 0 on success, and \-1 on failure, with
139 .BR set_thread_area ()
142 .BR get_thread_area ()
143 returns the thread area pointer value
145 .BR set_thread_area ()).
149 \fIu_info\fP is an invalid pointer.
152 \fIu_info\->entry_number\fP is out of bounds.
155 .BR get_thread_area ()
157 .BR set_thread_area ()
158 was invoked as a 64-bit system call.
161 .RB ( set_thread_area ())
162 A free TLS entry could not be located.
164 .BR set_thread_area ()
165 first appeared in Linux 2.5.29.
166 .BR get_thread_area ()
167 first appeared in Linux 2.5.32.
169 .BR set_thread_area "() and " get_thread_area ()
170 are Linux-specific and should not be used in programs that are intended
173 Glibc does not provide wrappers for these system calls,
174 since they are generally intended for use only by threading libraries.
175 In the unlikely event that you want to call them directly, use
180 .BR set_thread_area ()
185 This is not normally a problem, as
187 is normally used only by 64-bit programs.
189 On MIPS, the current value of the thread area pointer can be obtained
190 using the instruction:
198 This instruction traps and is handled by kernel.
200 On 64-bit kernels before Linux 3.19,
201 .\" commit e30ab185c490e9a9381385529e0fd32f0a399495
202 one of the padding bits in
204 if set, would prevent the descriptor from being considered empty (see
206 As a result, the only reliable way to clear a TLS entry is to use
210 structure, including padding bits, and then to set the
217 consisting entirely of zeros except for
219 will also be interpreted as a request to clear a TLS entry, but this
220 behaved differently on older kernels.
222 Prior to Linux 3.19, the DS and ES segment registers must not reference
228 .RB ( PTRACE_GET_THREAD_AREA " and " PTRACE_SET_THREAD_AREA )