man2/set_thread_area.2

   1 .\" Copyright (C) 2003 Free Software Foundation, Inc.
   2 .\" Copyright (C) 2015 Andrew Lutomirski
   3 .\" Author: Kent Yoder
   4 .\"
   5 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   6 .\" This file is distributed according to the GNU General Public License.
   7 .\" %%%LICENSE_END
   8 .\"
   9 .TH SET_THREAD_AREA 2 2017-09-15 "Linux" "Linux Programmer's Manual"
  10 .SH NAME
  11 get_thread_area, set_thread_area \- manipulate thread-local storage information
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <linux/unistd.h>
  15
  16 .B #if defined __i386__ || defined __x86_64__
  17 .B # include <asm/ldt.h>
  18 .PP
  19 .BI "int get_thread_area(struct user_desc *" u_info );
  20 .BI "int set_thread_area(struct user_desc *" u_info );
  21 .PP
  22 .B #elif defined __m68k__
  23 .PP
  24 .B "int get_thread_area(void);
  25 .BI "int set_thread_area(unsigned long " tp );
  26 .PP
  27 .B #elif defined __mips__
  28 .PP
  29 .BI "int set_thread_area(unsigned long " addr );
  30 .PP
  31 .B #endif
  32 .fi
  33 .PP
  34 .IR Note :
  35 There are no glibc wrappers for these system calls; see NOTES.
  36 .SH DESCRIPTION
  37 These calls provide architecture-specific support for a thread-local storage
  38 implementation.
  39 At the moment,
  40 .BR set_thread_area ()
  41 is available on m68k, MIPS, and x86 (both 32-bit and 64-bit variants);
  42 .BR get_thread_area ()
  43 is available on m68k and x86.
  44 .PP
  45 On m68k and MIPS,
  46 .BR set_thread_area ()
  47 allows storing an arbitrary pointer (provided in the
  48 .B tp
  49 argument on m68k and in the
  50 .B addr
  51 argument on MIPS)
  52 in the kernel data structure associated with the calling thread;
  53 this pointer can later be retrieved using
  54 .BR get_thread_area ()
  55 (see also NOTES
  56 for information regarding obtaining the thread pointer on MIPS).
  57 .PP
  58 On x86, Linux dedicates three global descriptor table (GDT) entries for
  59 thread-local storage.
  60 For more information about the GDT, see the
  61 Intel Software Developer's Manual or the AMD Architecture Programming Manual.
  62 .PP
  63 Both of these system calls take an argument that is a pointer
  64 to a structure of the following type:
  65 .PP
  66 .in +4n
  67 .EX
  68 struct user_desc {
  69     unsigned int  entry_number;
  70     unsigned long base_addr;
  71     unsigned int  limit;
  72     unsigned int  seg_32bit:1;
  73     unsigned int  contents:2;
  74     unsigned int  read_exec_only:1;
  75     unsigned int  limit_in_pages:1;
  76     unsigned int  seg_not_present:1;
  77     unsigned int  useable:1;
  78 #ifdef __x86_64__
  79     unsigned int  lm:1;
  80 #endif
  81 };
  82 .EE
  83 .in
  84 .PP
  85 .BR get_thread_area ()
  86 reads the GDT entry indicated by
  87 .I u_info\->entry_number
  88 and fills in the rest of the fields in
  89 .IR u_info .
  90 .PP
  91 .BR set_thread_area ()
  92 sets a TLS entry in the GDT.
  93 .PP
  94 The TLS array entry set by
  95 .BR set_thread_area ()
  96 corresponds to the value of
  97 .I u_info\->entry_number
  98 passed in by the user.
  99 If this value is in bounds,
 100 .BR set_thread_area ()
 101 writes the TLS descriptor pointed to by
 102 .I u_info
 103 into the thread's TLS array.
 104 .PP
 105 When
 106 .BR set_thread_area ()
 107 is passed an
 108 .I entry_number
 109 of \-1, it searches for a free TLS entry.
 110 If
 111 .BR set_thread_area ()
 112 finds a free TLS entry, the value of
 113 .I u_info\->entry_number
 114 is set upon return to show which entry was changed.
 115 .PP
 116 A
 117 .I user_desc
 118 is considered "empty" if
 119 .I read_exec_only
 120 and
 121 .I seg_not_present
 122 are set to 1 and all of the other fields are 0.
 123 If an "empty" descriptor is passed to
 124 .BR set_thread_area,
 125 the corresponding TLS entry will be cleared.
 126 See BUGS for additional details.
 127 .PP
 128 Since Linux 3.19,
 129 .BR set_thread_area ()
 130 cannot be used to write non-present segments, 16-bit segments, or code
 131 segments, although clearing a segment is still acceptable.
 132 .SH RETURN VALUE
 133 On x86, these system calls
 134 return 0 on success, and \-1 on failure, with
 135 .I errno
 136 set appropriately.
 137 .PP
 138 On MIPS and m68k,
 139 .BR set_thread_area ()
 140 always returns 0.
 141 On m68k,
 142 .BR get_thread_area ()
 143 returns the thread area pointer value
 144 (previously set via
 145 .BR set_thread_area ()).
 146 .SH ERRORS
 147 .TP
 148 .B EFAULT
 149 \fIu_info\fP is an invalid pointer.
 150 .TP
 151 .B EINVAL
 152 \fIu_info\->entry_number\fP is out of bounds.
 153 .TP
 154 .B ENOSYS
 155 .BR get_thread_area ()
 156 or
 157 .BR set_thread_area ()
 158 was invoked as a 64-bit system call.
 159 .TP
 160 .B ESRCH
 161 .RB ( set_thread_area ())
 162 A free TLS entry could not be located.
 163 .SH VERSIONS
 164 .BR set_thread_area ()
 165 first appeared in Linux 2.5.29.
 166 .BR get_thread_area ()
 167 first appeared in Linux 2.5.32.
 168 .SH CONFORMING TO
 169 .BR set_thread_area ()
 170 and
 171 .BR get_thread_area ()
 172 are Linux-specific and should not be used in programs that are intended
 173 to be portable.
 174 .SH NOTES
 175 Glibc does not provide wrappers for these system calls,
 176 since they are generally intended for use only by threading libraries.
 177 In the unlikely event that you want to call them directly, use
 178 .BR syscall (2).
 179 .PP
 180 .BR arch_prctl (2)
 181 can interfere with
 182 .BR set_thread_area ()
 183 on x86.
 184 See
 185 .BR arch_prctl (2)
 186 for more details.
 187 This is not normally a problem, as
 188 .BR arch_prctl (2)
 189 is normally used only by 64-bit programs.
 190 .PP
 191 On MIPS, the current value of the thread area pointer can be obtained
 192 using the instruction:
 193 .PP
 194 .in +4n
 195 .EX
 196 rdhwr dest, $29
 197 .EE
 198 .in
 199 .PP
 200 This instruction traps and is handled by kernel.
 201 .SH BUGS
 202 On 64-bit kernels before Linux 3.19,
 203 .\" commit e30ab185c490e9a9381385529e0fd32f0a399495
 204 one of the padding bits in
 205 .IR user_desc ,
 206 if set, would prevent the descriptor from being considered empty (see
 207 .BR modify_ldt (2)).
 208 As a result, the only reliable way to clear a TLS entry is to use
 209 .BR memset (3)
 210 to zero the entire
 211 .I user_desc
 212 structure, including padding bits, and then to set the
 213 .I read_exec_only
 214 and
 215 .I seg_not_present
 216 bits.
 217 On Linux 3.19, a
 218 .I user_desc
 219 consisting entirely of zeros except for
 220 .I entry_number
 221 will also be interpreted as a request to clear a TLS entry, but this
 222 behaved differently on older kernels.
 223 .PP
 224 Prior to Linux 3.19, the DS and ES segment registers must not reference
 225 TLS entries.
 226 .SH SEE ALSO
 227 .BR arch_prctl (2),
 228 .BR modify_ldt (2),
 229 .BR ptrace (2)
 230 .RB ( PTRACE_GET_THREAD_AREA " and " PTRACE_SET_THREAD_AREA )