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 2015-02-21 "Linux" "Linux Programmer's Manual"
  10 .SH NAME
  11 set_thread_area \- set a GDT entry for thread-local storage
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <linux/unistd.h>
  15 .B #include <asm/ldt.h>
  16
  17 .BI "int get_thread_area(struct user_desc *" u_info );
  18 .BI "int set_thread_area(struct user_desc *" u_info );
  19 .fi
  20
  21 .IR Note :
  22 There are no glibc wrappers for these system calls; see NOTES.
  23 .SH DESCRIPTION
  24 Linux dedicates three global descriptor table (GDT) entries for
  25 thread-local storage.
  26 For more information about the GDT, see the
  27 Intel Software Developer's Manual or the AMD Architecture Programming Manual.
  28
  29 Both of these system calls take an argument that is a pointer
  30 to a structure of the following type:
  31
  32 .in +4n
  33 struct user_desc {
  34     unsigned int  entry_number;
  35     unsigned long base_addr;
  36     unsigned int  limit;
  37     unsigned int  seg_32bit:1;
  38     unsigned int  contents:2;
  39     unsigned int  read_exec_only:1;
  40     unsigned int  limit_in_pages:1;
  41     unsigned int  seg_not_present:1;
  42     unsigned int  useable:1;
  43 };
  44 .in
  45
  46 .BR get_thread_area ()
  47 reads the GDT entry indicated by
  48 .I u_info\->entry_number
  49 and fills in the rest of the fields in
  50 .IR u_info .
  51
  52 .BR set_thread_area ()
  53 sets a TLS entry in the GDT.
  54 .PP
  55 The TLS array entry set by
  56 .BR set_thread_area ()
  57 corresponds to the value of
  58 .I u_info\->entry_number
  59 passed in by the user.
  60 If this value is in bounds,
  61 .BR set_thread_area ()
  62 writes the TLS descriptor pointed to by
  63 .I u_info
  64 into the thread's TLS array.
  65 .PP
  66 When
  67 .BR set_thread_area ()
  68 is passed an
  69 .I entry_number
  70 of \-1, it searches for a free TLS entry.
  71 If
  72 .BR set_thread_area ()
  73 finds a free TLS entry, the value of
  74 .I u_info\->entry_number
  75 is set upon return to show which entry was changed.
  76 .PP
  77 A
  78 .I user_desc
  79 is considered "empty" if
  80 .I read_exec_only
  81 and
  82 .I seg_not_present
  83 are set to 1 and all of the other fields are 0.
  84 If an "empty" descriptor is passed to
  85 .BR set_thread_area,
  86 the corresponding TLS entry will be cleared.
  87 See BUGS for additional details.
  88 .PP
  89 Since Linux 3.19,
  90 .BR set_thread_area ()
  91 cannot be used to write non-present segments, 16-bit segments, or code
  92 segments, although clearing a segment is still acceptable.
  93 .SH RETURN VALUE
  94 These system calls
  95 return 0 on success, and \-1 on failure, with
  96 .I errno
  97 set appropriately.
  98 .SH ERRORS
  99 .TP
 100 .B EFAULT
 101 \fIu_info\fP is an invalid pointer.
 102 .TP
 103 .B EINVAL
 104 \fIu_info\->entry_number\fP is out of bounds.
 105 .TP
 106 .B ENOSYS
 107 .BR get_thread_area (2)
 108 or
 109 .BR set_thread_area (2)
 110 was invoked as a 64-bit system call.
 111 .TP
 112 .B ESRCH
 113 .RB ( set_thread_area ())
 114 A free TLS entry could not be located.
 115 .SH VERSIONS
 116 .BR set_thread_area ()
 117 first appeared in Linux 2.5.29.
 118 .BR get_thread_area ()
 119 first appeared in Linux 2.5.32.
 120 .SH CONFORMING TO
 121 .BR set_thread_area ()
 122 is Linux-specific and should not be used in programs that are intended
 123 to be portable.
 124 .SH NOTES
 125 Glibc does not provide wrappers for these system calls,
 126 since they are generally intended for use only by threading libraries.
 127 In the unlikely event that you want to call them directly, use
 128 .BR syscall (2).
 129 .PP
 130 .BR arch_prctl (2)
 131 can interfere with
 132 .BR set_thread_area (2).
 133 See
 134 .BR arch_prctl (2)
 135 for more details.
 136 This is not normally a problem, as
 137 .BR arch_prctl (2)
 138 is normally used only by 64-bit programs.
 139 .SH BUGS
 140 On 64-bit kernels before Linux 3.19,
 141 .\" commit e30ab185c490e9a9381385529e0fd32f0a399495
 142 one of the padding bits in
 143 .IR user_desc ,
 144 if set, would prevent the descriptor from being considered empty (see
 145 .BR modify_ldt (2)).
 146 As a result, the only reliable way to clear a TLS entry is to use
 147 .BR memset (3)
 148 to zero the entire
 149 .I user_desc
 150 structure, including padding bits, and then to set the
 151 .I read_exec_only
 152 and
 153 .I seg_not_present
 154 bits.
 155 On Linux 3.19, a
 156 .I user_desc
 157 consisting entirely of zeros except for
 158 .I entry_number
 159 will also be interpreted as a request to clear a TLS entry, but this
 160 behaved differently on older kernels.
 161 .PP
 162 Prior to Linux 3.19, the DS and ES segment registers must not reference
 163 TLS entries.
 164 .SH SEE ALSO
 165 .BR arch_prctl (2),
 166 .BR modify_ldt (2)