1SET_THREAD_AREA(2) Linux Programmer's Manual SET_THREAD_AREA(2)
2
6 get_thread_area, set_thread_area - manipulate thread-local storage in‐
7 formation
8
10 #include <sys/syscall.h> /* Definition of SYS_* constants */
11 #include <unistd.h>
12 #if defined __i386__ || defined __x86_64__
14 # include <asm/ldt.h> /* Definition of struct user_desc */
15 int syscall(SYS_get_thread_area, struct user_desc *u_info);
17 int syscall(SYS_set_thread_area, struct user_desc *u_info);
18 #elif defined __m68k__
20 int syscall(SYS_get_thread_area);
22 int syscall(SYS_set_thread_area, unsigned long tp);
23 #elif defined __mips__
25 int syscall(SYS_set_thread_area, unsigned long addr);
27 #endif
29 Note: glibc provides no wrappers for these system calls, necessitating
31 the use of syscall(2).
32
34 These calls provide architecture-specific support for a thread-local
35 storage implementation. At the moment, set_thread_area() is available
36 on m68k, MIPS, and x86 (both 32-bit and 64-bit variants);
37 get_thread_area() is available on m68k and x86.
38 On m68k and MIPS, set_thread_area() allows storing an arbitrary pointer
40 (provided in the tp argument on m68k and in the addr argument on MIPS)
41 in the kernel data structure associated with the calling thread; this
42 pointer can later be retrieved using get_thread_area() (see also NOTES
43 for information regarding obtaining the thread pointer on MIPS).
44 On x86, Linux dedicates three global descriptor table (GDT) entries for
46 thread-local storage. For more information about the GDT, see the In‐
47 tel Software Developer's Manual or the AMD Architecture Programming
48 Manual.
49 Both of these system calls take an argument that is a pointer to a
51 structure of the following type:
52 struct user_desc {
54 unsigned int entry_number;
55 unsigned int base_addr;
56 unsigned int limit;
57 unsigned int seg_32bit:1;
58 unsigned int contents:2;
59 unsigned int read_exec_only:1;
60 unsigned int limit_in_pages:1;
61 unsigned int seg_not_present:1;
62 unsigned int useable:1;
63 #ifdef __x86_64__
64 unsigned int lm:1;
65 #endif
66 };
67 get_thread_area() reads the GDT entry indicated by u_info->entry_number
69 and fills in the rest of the fields in u_info.
70 set_thread_area() sets a TLS entry in the GDT.
72 The TLS array entry set by set_thread_area() corresponds to the value
74 of u_info->entry_number passed in by the user. If this value is in
75 bounds, set_thread_area() writes the TLS descriptor pointed to by
76 u_info into the thread's TLS array.
77 When set_thread_area() is passed an entry_number of -1, it searches for
79 a free TLS entry. If set_thread_area() finds a free TLS entry, the
80 value of u_info->entry_number is set upon return to show which entry
81 was changed.
82 A user_desc is considered "empty" if read_exec_only and seg_not_present
84 are set to 1 and all of the other fields are 0. If an "empty" descrip‐
85 tor is passed to set_thread_area(), the corresponding TLS entry will be
86 cleared. See BUGS for additional details.
87 Since Linux 3.19, set_thread_area() cannot be used to write non-present
89 segments, 16-bit segments, or code segments, although clearing a seg‐
90 ment is still acceptable.
91
93 On x86, these system calls return 0 on success, and -1 on failure, with
94 errno set to indicate the error.
95 On MIPS and m68k, set_thread_area() always returns 0. On m68k,
97 get_thread_area() returns the thread area pointer value (previously set
98 via set_thread_area()).
99
101 EFAULT u_info is an invalid pointer.
102 EINVAL u_info->entry_number is out of bounds.
104 ENOSYS get_thread_area() or set_thread_area() was invoked as a 64-bit
106 system call.
107 ESRCH (set_thread_area()) A free TLS entry could not be located.
109
111 set_thread_area() first appeared in Linux 2.5.29. get_thread_area()
112 first appeared in Linux 2.5.32.
113
115 set_thread_area() and get_thread_area() are Linux-specific and should
116 not be used in programs that are intended to be portable.
117
119 These system calls are generally intended for use only by threading li‐
120 braries.
121 arch_prctl(2) can interfere with set_thread_area() on x86. See
123 arch_prctl(2) for more details. This is not normally a problem, as
124 arch_prctl(2) is normally used only by 64-bit programs.
125 On MIPS, the current value of the thread area pointer can be obtained
127 using the instruction:
128 rdhwr dest, $29
130 This instruction traps and is handled by kernel.
132
134 On 64-bit kernels before Linux 3.19, one of the padding bits in
135 user_desc, if set, would prevent the descriptor from being considered
136 empty (see modify_ldt(2)). As a result, the only reliable way to clear
137 a TLS entry is to use memset(3) to zero the entire user_desc structure,
138 including padding bits, and then to set the read_exec_only and
139 seg_not_present bits. On Linux 3.19, a user_desc consisting entirely
140 of zeros except for entry_number will also be interpreted as a request
141 to clear a TLS entry, but this behaved differently on older kernels.
142 Prior to Linux 3.19, the DS and ES segment registers must not reference
144 TLS entries.
145
147 arch_prctl(2), modify_ldt(2), ptrace(2) (PTRACE_GET_THREAD_AREA and
148 PTRACE_SET_THREAD_AREA)
149
151 This page is part of release 5.12 of the Linux man-pages project. A
152 description of the project, information about reporting bugs, and the
153 latest version of this page, can be found at
154 https://www.kernel.org/doc/man-pages/.
155Linux 2021-03-22 SET_THREAD_AREA(2)