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

NAME

6       get_thread_area,  set_thread_area - manipulate thread-local storage in‐
7       formation
8

SYNOPSIS

10       #include <linux/unistd.h>
11
12       #if defined __i386__ || defined __x86_64__
13       # include <asm/ldt.h>
14
15       int get_thread_area(struct user_desc *u_info);
16       int set_thread_area(struct user_desc *u_info);
17
18       #elif defined __m68k__
19
20       int get_thread_area(void);
21       int set_thread_area(unsigned long tp);
22
23       #elif defined __mips__
24
25       int set_thread_area(unsigned long addr);
26
27       #endif
28
29       Note: There are no glibc wrappers for these system calls; see NOTES.
30

DESCRIPTION

32       These calls provide architecture-specific support  for  a  thread-local
33       storage  implementation.  At the moment, set_thread_area() is available
34       on  m68k,  MIPS,  and  x86   (both   32-bit   and   64-bit   variants);
35       get_thread_area() is available on m68k and x86.
36
37       On m68k and MIPS, set_thread_area() allows storing an arbitrary pointer
38       (provided in the tp argument on m68k and in the addr argument on  MIPS)
39       in  the  kernel data structure associated with the calling thread; this
40       pointer can later be retrieved using get_thread_area() (see also  NOTES
41       for information regarding obtaining the thread pointer on MIPS).
42
43       On x86, Linux dedicates three global descriptor table (GDT) entries for
44       thread-local storage.  For more information about the GDT, see the  In‐
45       tel  Software  Developer's  Manual  or the AMD Architecture Programming
46       Manual.
47
48       Both of these system calls take an argument that  is  a  pointer  to  a
49       structure of the following type:
50
51           struct user_desc {
52               unsigned int  entry_number;
53               unsigned int  base_addr;
54               unsigned int  limit;
55               unsigned int  seg_32bit:1;
56               unsigned int  contents:2;
57               unsigned int  read_exec_only:1;
58               unsigned int  limit_in_pages:1;
59               unsigned int  seg_not_present:1;
60               unsigned int  useable:1;
61           #ifdef __x86_64__
62               unsigned int  lm:1;
63           #endif
64           };
65
66       get_thread_area() reads the GDT entry indicated by u_info->entry_number
67       and fills in the rest of the fields in u_info.
68
69       set_thread_area() sets a TLS entry in the GDT.
70
71       The TLS array entry set by set_thread_area() corresponds to  the  value
72       of  u_info->entry_number  passed  in  by the user.  If this value is in
73       bounds, set_thread_area() writes  the  TLS  descriptor  pointed  to  by
74       u_info into the thread's TLS array.
75
76       When set_thread_area() is passed an entry_number of -1, it searches for
77       a free TLS entry.  If set_thread_area() finds a  free  TLS  entry,  the
78       value  of  u_info->entry_number  is set upon return to show which entry
79       was changed.
80
81       A user_desc is considered "empty" if read_exec_only and seg_not_present
82       are set to 1 and all of the other fields are 0.  If an "empty" descrip‐
83       tor is passed to set_thread_area(), the corresponding TLS entry will be
84       cleared.  See BUGS for additional details.
85
86       Since Linux 3.19, set_thread_area() cannot be used to write non-present
87       segments, 16-bit segments, or code segments, although clearing  a  seg‐
88       ment is still acceptable.
89

RETURN VALUE

91       On x86, these system calls return 0 on success, and -1 on failure, with
92       errno set appropriately.
93
94       On MIPS  and  m68k,  set_thread_area()  always  returns  0.   On  m68k,
95       get_thread_area() returns the thread area pointer value (previously set
96       via set_thread_area()).
97

ERRORS

99       EFAULT u_info is an invalid pointer.
100
101       EINVAL u_info->entry_number is out of bounds.
102
103       ENOSYS get_thread_area() or set_thread_area() was invoked as  a  64-bit
104              system call.
105
106       ESRCH  (set_thread_area()) A free TLS entry could not be located.
107

VERSIONS

109       set_thread_area()  first  appeared  in Linux 2.5.29.  get_thread_area()
110       first appeared in Linux 2.5.32.
111

CONFORMING TO

113       set_thread_area() and get_thread_area() are Linux-specific  and  should
114       not be used in programs that are intended to be portable.
115

NOTES

117       Glibc  does not provide wrappers for these system calls, since they are
118       generally intended for use only by threading  libraries.   In  the  un‐
119       likely event that you want to call them directly, use syscall(2).
120
121       arch_prctl(2)   can  interfere  with  set_thread_area()  on  x86.   See
122       arch_prctl(2) for more details.  This is not  normally  a  problem,  as
123       arch_prctl(2) is normally used only by 64-bit programs.
124
125       On  MIPS,  the current value of the thread area pointer can be obtained
126       using the instruction:
127
128           rdhwr dest, $29
129
130       This instruction traps and is handled by kernel.
131

BUGS

133       On 64-bit kernels before  Linux  3.19,  one  of  the  padding  bits  in
134       user_desc,  if  set, would prevent the descriptor from being considered
135       empty (see modify_ldt(2)).  As a result, the only reliable way to clear
136       a TLS entry is to use memset(3) to zero the entire user_desc structure,
137       including  padding  bits,  and  then  to  set  the  read_exec_only  and
138       seg_not_present  bits.   On Linux 3.19, a user_desc consisting entirely
139       of zeros except for entry_number will also be interpreted as a  request
140       to clear a TLS entry, but this behaved differently on older kernels.
141
142       Prior to Linux 3.19, the DS and ES segment registers must not reference
143       TLS entries.
144

SEE ALSO

146       arch_prctl(2),  modify_ldt(2),  ptrace(2)  (PTRACE_GET_THREAD_AREA  and
147       PTRACE_SET_THREAD_AREA)
148

COLOPHON

150       This  page  is  part of release 5.10 of the Linux man-pages project.  A
151       description of the project, information about reporting bugs,  and  the
152       latest     version     of     this    page,    can    be    found    at
153       https://www.kernel.org/doc/man-pages/.
154
155
156
157Linux                             2020-02-09                SET_THREAD_AREA(2)
Impressum