Debian Codegraph @

upstream/debian-trixie/man3/pthread_getattr_np.3

raw
1 '\" t
2 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
3 .\" <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH pthread_getattr_np 3 2024-06-15 "Linux man-pages 6.9.1"
8 .SH NAME
9 pthread_getattr_np \- get attributes of created thread
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ", " \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
16 .B #include <pthread.h>
17 .P
18 .BI "int pthread_getattr_np(pthread_t " thread ", pthread_attr_t *" attr );
19 .fi
20 .SH DESCRIPTION
21 The
22 .BR pthread_getattr_np ()
23 function initializes the thread attributes object referred to by
24 .I attr
25 so that it contains actual attribute values describing the running thread
26 .IR thread .
27 .P
28 The returned attribute values may differ from
29 the corresponding attribute values passed in the
30 .I attr
31 object that was used to create the thread using
32 .BR pthread_create (3).
33 In particular, the following attributes may differ:
34 .IP \[bu] 3
35 the detach state, since a joinable thread may have detached itself
36 after creation;
37 .IP \[bu]
38 the stack size,
39 which the implementation may align to a suitable boundary.
40 .IP \[bu]
41 and the guard size,
42 which the implementation may round upward to a multiple of the page size,
43 or ignore (i.e., treat as 0),
44 if the application is allocating its own stack.
45 .P
46 Furthermore, if the stack address attribute was not set
47 in the thread attributes object used to create the thread,
48 then the returned thread attributes object will report the actual
49 stack address that the implementation selected for the thread.
50 .P
51 When the thread attributes object returned by
52 .BR pthread_getattr_np ()
53 is no longer required, it should be destroyed using
54 .BR pthread_attr_destroy (3).
55 .SH RETURN VALUE
56 On success, this function returns 0;
57 on error, it returns a nonzero error number.
58 .SH ERRORS
59 .TP
60 .B ENOMEM
61 .\" Can happen (but unlikely) while trying to allocate memory for cpuset
62 Insufficient memory.
63 .P
64 In addition, if
65 .I thread
66 refers to the main thread, then
67 .BR pthread_getattr_np ()
68 can fail because of errors from various underlying calls:
69 .BR fopen (3),
70 if
71 .I /proc/self/maps
72 can't be opened;
73 and
74 .BR getrlimit (2),
75 if the
76 .B RLIMIT_STACK
77 resource limit is not supported.
78 .SH ATTRIBUTES
79 For an explanation of the terms used in this section, see
80 .BR attributes (7).
81 .TS
82 allbox;
83 lbx lb lb
84 l l l.
85 Interface Attribute Value
86 T{
87 .na
88 .nh
89 .BR pthread_getattr_np ()
90 T} Thread safety MT-Safe
91 .TE
92 .SH STANDARDS
93 GNU;
94 hence the suffix "_np" (nonportable) in the name.
95 .SH HISTORY
96 glibc 2.2.3.
97 .SH EXAMPLES
98 The program below demonstrates the use of
99 .BR pthread_getattr_np ().
100 The program creates a thread that then uses
101 .BR pthread_getattr_np ()
102 to retrieve and display its guard size, stack address,
103 and stack size attributes.
104 Command-line arguments can be used to set these attributes
105 to values other than the default when creating the thread.
106 The shell sessions below demonstrate the use of the program.
107 .P
108 In the first run, on an x86-32 system,
109 a thread is created using default attributes:
110 .P
111 .in +4n
112 .EX
113 .RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB"
114 unlimited
115 .RB "$" " ./a.out"
116 Attributes of created thread:
117 Guard size = 4096 bytes
118 Stack address = 0x40196000 (EOS = 0x40397000)
119 Stack size = 0x201000 (2101248) bytes
120 .EE
121 .in
122 .P
123 In the following run, we see that if a guard size is specified,
124 it is rounded up to the next multiple of the system page size
125 (4096 bytes on x86-32):
126 .P
127 .in +4n
128 .EX
129 .RB "$" " ./a.out \-g 4097"
130 Thread attributes object after initializations:
131 Guard size = 4097 bytes
132 Stack address = (nil)
133 Stack size = 0x0 (0) bytes
134 \&
135 Attributes of created thread:
136 Guard size = 8192 bytes
137 Stack address = 0x40196000 (EOS = 0x40397000)
138 Stack size = 0x201000 (2101248) bytes
139 .EE
140 .in
141 .\".in +4n
142 .\".nf
143 .\"$ ./a.out \-s 0x8000
144 .\"Thread attributes object after initializations:
145 .\" Guard size = 4096 bytes
146 .\" Stack address = 0xffff8000 (EOS = (nil))
147 .\" Stack size = 0x8000 (32768) bytes
148 .\"
149 .\"Attributes of created thread:
150 .\" Guard size = 4096 bytes
151 .\" Stack address = 0x4001e000 (EOS = 0x40026000)
152 .\" Stack size = 0x8000 (32768) bytes
153 .\".fi
154 .\".in
155 .P
156 In the last run, the program manually allocates a stack for the thread.
157 In this case, the guard size attribute is ignored.
158 .P
159 .in +4n
160 .EX
161 .RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a"
162 Allocated thread stack at 0x804d000
163 \&
164 Thread attributes object after initializations:
165 Guard size = 4096 bytes
166 Stack address = 0x804d000 (EOS = 0x8055000)
167 Stack size = 0x8000 (32768) bytes
168 \&
169 Attributes of created thread:
170 Guard size = 0 bytes
171 Stack address = 0x804d000 (EOS = 0x8055000)
172 Stack size = 0x8000 (32768) bytes
173 .EE
174 .in
175 .SS Program source
176 \&
177 .\" SRC BEGIN (pthread_getattr_np.c)
178 .EX
179 #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */
180 #include <err.h>
181 #include <errno.h>
182 #include <pthread.h>
183 #include <stdio.h>
184 #include <stdlib.h>
185 #include <unistd.h>
186 \&
187 static void
188 display_stack_related_attributes(pthread_attr_t *attr, char *prefix)
189 {
190 int s;
191 size_t stack_size, guard_size;
192 void *stack_addr;
193 \&
194 s = pthread_attr_getguardsize(attr, &guard_size);
195 if (s != 0)
196 errc(EXIT_FAILURE, s, "pthread_attr_getguardsize");
197 printf("%sGuard size = %zu bytes\[rs]n", prefix, guard_size);
198 \&
199 s = pthread_attr_getstack(attr, &stack_addr, &stack_size);
200 if (s != 0)
201 errc(EXIT_FAILURE, s, "pthread_attr_getstack");
202 printf("%sStack address = %p", prefix, stack_addr);
203 if (stack_size > 0)
204 printf(" (EOS = %p)", (char *) stack_addr + stack_size);
205 printf("\[rs]n");
206 printf("%sStack size = %#zx (%zu) bytes\[rs]n",
207 prefix, stack_size, stack_size);
208 }
209 \&
210 static void
211 display_thread_attributes(pthread_t thread, char *prefix)
212 {
213 int s;
214 pthread_attr_t attr;
215 \&
216 s = pthread_getattr_np(thread, &attr);
217 if (s != 0)
218 errc(EXIT_FAILURE, s, "pthread_getattr_np");
219 \&
220 display_stack_related_attributes(&attr, prefix);
221 \&
222 s = pthread_attr_destroy(&attr);
223 if (s != 0)
224 errc(EXIT_FAILURE, s, "pthread_attr_destroy");
225 }
226 \&
227 static void * /* Start function for thread we create */
228 thread_start(void *arg)
229 {
230 printf("Attributes of created thread:\[rs]n");
231 display_thread_attributes(pthread_self(), "\[rs]t");
232 \&
233 exit(EXIT_SUCCESS); /* Terminate all threads */
234 }
235 \&
236 static void
237 usage(char *pname, char *msg)
238 {
239 if (msg != NULL)
240 fputs(msg, stderr);
241 fprintf(stderr, "Usage: %s [\-s stack\-size [\-a]]"
242 " [\-g guard\-size]\[rs]n", pname);
243 fprintf(stderr, "\[rs]t\[rs]t\-a means program should allocate stack\[rs]n");
244 exit(EXIT_FAILURE);
245 }
246 \&
247 static pthread_attr_t * /* Get thread attributes from command line */
248 get_thread_attributes_from_cl(int argc, char *argv[],
249 pthread_attr_t *attrp)
250 {
251 int s, opt, allocate_stack;
252 size_t stack_size, guard_size;
253 void *stack_addr;
254 pthread_attr_t *ret_attrp = NULL; /* Set to attrp if we initialize
255 a thread attributes object */
256 allocate_stack = 0;
257 stack_size = \-1;
258 guard_size = \-1;
259 \&
260 while ((opt = getopt(argc, argv, "ag:s:")) != \-1) {
261 switch (opt) {
262 case \[aq]a\[aq]: allocate_stack = 1; break;
263 case \[aq]g\[aq]: guard_size = strtoul(optarg, NULL, 0); break;
264 case \[aq]s\[aq]: stack_size = strtoul(optarg, NULL, 0); break;
265 default: usage(argv[0], NULL);
266 }
267 }
268 \&
269 if (allocate_stack && stack_size == \-1)
270 usage(argv[0], "Specifying \-a without \-s makes no sense\[rs]n");
271 \&
272 if (argc > optind)
273 usage(argv[0], "Extraneous command\-line arguments\[rs]n");
274 \&
275 if (stack_size != -1 || guard_size > 0) {
276 ret_attrp = attrp;
277 \&
278 s = pthread_attr_init(attrp);
279 if (s != 0)
280 errc(EXIT_FAILURE, s, "pthread_attr_init");
281 }
282 \&
283 if (stack_size != -1) {
284 if (!allocate_stack) {
285 s = pthread_attr_setstacksize(attrp, stack_size);
286 if (s != 0)
287 errc(EXIT_FAILURE, s, "pthread_attr_setstacksize");
288 } else {
289 s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE),
290 stack_size);
291 if (s != 0)
292 errc(EXIT_FAILURE, s, "posix_memalign");
293 printf("Allocated thread stack at %p\[rs]n\[rs]n", stack_addr);
294 \&
295 s = pthread_attr_setstack(attrp, stack_addr, stack_size);
296 if (s != 0)
297 errc(EXIT_FAILURE, s, "pthread_attr_setstacksize");
298 }
299 }
300 \&
301 if (guard_size != -1) {
302 s = pthread_attr_setguardsize(attrp, guard_size);
303 if (s != 0)
304 errc(EXIT_FAILURE, s, "pthread_attr_setstacksize");
305 }
306 \&
307 return ret_attrp;
308 }
309 \&
310 int
311 main(int argc, char *argv[])
312 {
313 int s;
314 pthread_t thr;
315 pthread_attr_t attr;
316 pthread_attr_t *attrp = NULL; /* Set to &attr if we initialize
317 a thread attributes object */
318 \&
319 attrp = get_thread_attributes_from_cl(argc, argv, &attr);
320 \&
321 if (attrp != NULL) {
322 printf("Thread attributes object after initializations:\[rs]n");
323 display_stack_related_attributes(attrp, "\[rs]t");
324 printf("\[rs]n");
325 }
326 \&
327 s = pthread_create(&thr, attrp, &thread_start, NULL);
328 if (s != 0)
329 errc(EXIT_FAILURE, s, "pthread_create");
330 \&
331 if (attrp != NULL) {
332 s = pthread_attr_destroy(attrp);
333 if (s != 0)
334 errc(EXIT_FAILURE, s, "pthread_attr_destroy");
335 }
336 \&
337 pause(); /* Terminates when other thread calls exit() */
338 }
339 .EE
340 .\" SRC END
341 .SH SEE ALSO
342 .ad l
343 .nh
344 .BR pthread_attr_getaffinity_np (3),
345 .BR pthread_attr_getdetachstate (3),
346 .BR pthread_attr_getguardsize (3),
347 .BR pthread_attr_getinheritsched (3),
348 .BR pthread_attr_getschedparam (3),
349 .BR pthread_attr_getschedpolicy (3),
350 .BR pthread_attr_getscope (3),
351 .BR pthread_attr_getstack (3),
352 .BR pthread_attr_getstackaddr (3),
353 .BR pthread_attr_getstacksize (3),
354 .BR pthread_attr_init (3),
355 .BR pthread_create (3),
356 .BR pthreads (7)