Debian Codegraph @

upstream/debian-unstable/man3/pthread_getattr_np.3

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