1SET_THREAD_AREA(2)         Linux Programmer's Manual        SET_THREAD_AREA(2)
2
3
4

NAME

6       get_thread_area,  set_thread_area  -  set  a GDT entry for thread-local
7       storage
8

SYNOPSIS

10       #include <linux/unistd.h>
11       #include <asm/ldt.h>
12
13       int get_thread_area(struct user_desc *u_info);
14       int set_thread_area(struct user_desc *u_info);
15
16       Note: There are no glibc wrappers for these system calls; see NOTES.
17

DESCRIPTION

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
23       Both of these system calls take an argument that  is  a  pointer  to  a
24       structure of the following type:
25
26           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
38       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
41       set_thread_area() sets a TLS entry in the GDT.
42
43       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
48       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
53       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
58       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

RETURN VALUE

63       These  system  calls return 0 on success, and -1 on failure, with errno
64       set appropriately.
65

ERRORS

67       EFAULT u_info is an invalid pointer.
68
69       EINVAL u_info->entry_number is out of bounds.
70
71       ENOSYS get_thread_area() or set_thread_area() was invoked as  a  64-bit
72              system call.
73
74       ESRCH  (set_thread_area()) A free TLS entry could not be located.
75

VERSIONS

77       set_thread_area()  first  appeared  in Linux 2.5.29.  get_thread_area()
78       first appeared in Linux 2.5.32.
79

CONFORMING TO

81       set_thread_area() is Linux-specific and should not be used in  programs
82       that are intended to be portable.
83

NOTES

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
89       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

BUGS

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
103       Prior to Linux 3.19, the DS and ES segment registers must not reference
104       TLS entries.
105

SEE ALSO

107       arch_prctl(2), modify_ldt(2)
108

COLOPHON

110       This  page  is  part of release 4.15 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/.
114
115
116
117Linux                             2017-09-15                SET_THREAD_AREA(2)
Impressum