1SET_THREAD_AREA(2) Linux Programmer's Manual SET_THREAD_AREA(2)
2
6 get_thread_area, set_thread_area - set a GDT entry for thread-local
7 storage
8
10 #include <linux/unistd.h>
11 #include <asm/ldt.h>
12 int get_thread_area(struct user_desc *u_info);
14 int set_thread_area(struct user_desc *u_info);
15 Note: There are no glibc wrappers for these system calls; see NOTES.
17
19 Linux dedicates three global descriptor table (GDT) entries for thread-
20 local storage. For more information about the GDT, see the Intel Soft‐
21 ware Developer's Manual or the AMD Architecture Programming Manual.
22 Both of these system calls take an argument that is a pointer to a
24 structure of the following type:
25 struct user_desc {
27 unsigned int entry_number;
28 unsigned long base_addr;
29 unsigned int limit;
30 unsigned int seg_32bit:1;
31 unsigned int contents:2;
32 unsigned int read_exec_only:1;
33 unsigned int limit_in_pages:1;
34 unsigned int seg_not_present:1;
35 unsigned int useable:1;
36 };
37 get_thread_area() reads the GDT entry indicated by u_info->entry_number
39 and fills in the rest of the fields in u_info.
40 set_thread_area() sets a TLS entry in the GDT.
42 The TLS array entry set by set_thread_area() corresponds to the value
44 of u_info->entry_number passed in by the user. If this value is in
45 bounds, set_thread_area() writes the TLS descriptor pointed to by
46 u_info into the thread's TLS array.
47 When set_thread_area() is passed an entry_number of -1, it searches for
49 a free TLS entry. If set_thread_area() finds a free TLS entry, the
50 value of u_info->entry_number is set upon return to show which entry
51 was changed.
52 A user_desc is considered "empty" if read_exec_only and seg_not_present
54 are set to 1 and all of the other fields are 0. If an "empty" descrip‐
55 tor is passed to set_thread_area, the corresponding TLS entry will be
56 cleared. See BUGS for additional details.
57 Since Linux 3.19, set_thread_area() cannot be used to write non-present
59 segments, 16-bit segments, or code segments, although clearing a seg‐
60 ment is still acceptable.
61
63 These system calls return 0 on success, and -1 on failure, with errno
64 set appropriately.
65
67 EFAULT u_info is an invalid pointer.
68 EINVAL u_info->entry_number is out of bounds.
70 ENOSYS get_thread_area() or set_thread_area() was invoked as a 64-bit
72 system call.
73 ESRCH (set_thread_area()) A free TLS entry could not be located.
75
77 set_thread_area() first appeared in Linux 2.5.29. get_thread_area()
78 first appeared in Linux 2.5.32.
79
81 set_thread_area() is Linux-specific and should not be used in programs
82 that are intended to be portable.
83
85 Glibc does not provide wrappers for these system calls, since they are
86 generally intended for use only by threading libraries. In the
87 unlikely event that you want to call them directly, use syscall(2).
88 arch_prctl(2) can interfere with set_thread_area(). See arch_prctl(2)
90 for more details. This is not normally a problem, as arch_prctl(2) is
91 normally used only by 64-bit programs.
92
94 On 64-bit kernels before Linux 3.19, one of the padding bits in
95 user_desc, if set, would prevent the descriptor from being considered
96 empty (see modify_ldt(2)). As a result, the only reliable way to clear
97 a TLS entry is to use memset(3) to zero the entire user_desc structure,
98 including padding bits, and then to set the read_exec_only and
99 seg_not_present bits. On Linux 3.19, a user_desc consisting entirely
100 of zeros except for entry_number will also be interpreted as a request
101 to clear a TLS entry, but this behaved differently on older kernels.
102 Prior to Linux 3.19, the DS and ES segment registers must not reference
104 TLS entries.
105
107 arch_prctl(2), modify_ldt(2)
108
110 This page is part of release 4.16 of the Linux man-pages project. A
111 description of the project, information about reporting bugs, and the
112 latest version of this page, can be found at
113 https://www.kernel.org/doc/man-pages/.
114Linux 2017-09-15 SET_THREAD_AREA(2)