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 <sys/syscall.h>     /* Definition of SYS_* constants */
11       #include <unistd.h>
12
13       #if defined __i386__ || defined __x86_64__
14       # include <asm/ldt.h>        /* Definition of struct user_desc */
15
16       int syscall(SYS_get_thread_area, struct user_desc *u_info);
17       int syscall(SYS_set_thread_area, struct user_desc *u_info);
18
19       #elif defined __m68k__
20
21       int syscall(SYS_get_thread_area);
22       int syscall(SYS_set_thread_area, unsigned long tp);
23
24       #elif defined __mips__
25
26       int syscall(SYS_set_thread_area, unsigned long addr);
27
28       #endif
29
30       Note: glibc provides no wrappers for these system calls,  necessitating
31       the use of syscall(2).
32

DESCRIPTION

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
39       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
45       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
50       Both  of  these  system  calls  take an argument that is a pointer to a
51       structure of the following type:
52
53           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
68       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
71       set_thread_area() sets a TLS entry in the GDT.
72
73       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
78       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
83       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
88       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

RETURN VALUE

93       On x86, these system calls return 0 on success, and -1 on failure, with
94       errno set to indicate the error.
95
96       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

ERRORS

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

VERSIONS

111       set_thread_area() first appeared in  Linux  2.5.29.   get_thread_area()
112       first appeared in Linux 2.5.32.
113

CONFORMING TO

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

NOTES

119       These system calls are generally intended for use only by threading li‐
120       braries.
121
122       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
126       On  MIPS,  the current value of the thread area pointer can be obtained
127       using the instruction:
128
129           rdhwr dest, $29
130
131       This instruction traps and is handled by kernel.
132

BUGS

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

SEE ALSO

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

COLOPHON

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/.
155
156
157
158Linux                             2021-03-22                SET_THREAD_AREA(2)
Impressum