Debian Codegraph @

upstream/debian-trixie/man2/set_thread_area.2

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