1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .TH PTHREAD_GETATTR_NP 3 2021-03-22 "Linux" "Linux Programmer's Manual"
8 pthread_getattr_np \- get attributes of created thread
11 .RI ( libpthread ", " \-lpthread )
14 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
15 .B #include <pthread.h>
17 .BI "int pthread_getattr_np(pthread_t " thread ", pthread_attr_t *" attr );
21 .BR pthread_getattr_np ()
22 function initializes the thread attributes object referred to by
24 so that it contains actual attribute values describing the running thread
27 The returned attribute values may differ from
28 the corresponding attribute values passed in the
30 object that was used to create the thread using
31 .BR pthread_create (3).
32 In particular, the following attributes may differ:
34 the detach state, since a joinable thread may have detached itself
38 which the implementation may align to a suitable boundary.
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.
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.
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).
55 On success, this function returns 0;
56 on error, it returns a nonzero error number.
60 .\" Can happen (but unlikely) while trying to allocate memory for cpuset
65 refers to the main thread, then
66 .BR pthread_getattr_np ()
67 can fail because of errors from various underlying calls:
76 resource limit is not supported.
78 This function is available in glibc since version 2.2.3.
80 For an explanation of the terms used in this section, see
88 Interface Attribute Value
90 .BR pthread_getattr_np ()
91 T} Thread safety MT-Safe
97 This function is a nonstandard GNU extension;
98 hence the suffix "_np" (nonportable) in the name.
100 The program below demonstrates the use of
101 .BR pthread_getattr_np ().
102 The program creates a thread that then uses
103 .BR pthread_getattr_np ()
104 to retrieve and display its guard size, stack address,
105 and stack size attributes.
106 Command-line arguments can be used to set these attributes
107 to values other than the default when creating the thread.
108 The shell sessions below demonstrate the use of the program.
110 In the first run, on an x86-32 system,
111 a thread is created using default attributes:
115 .RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB"
118 Attributes of created thread:
119 Guard size = 4096 bytes
120 Stack address = 0x40196000 (EOS = 0x40397000)
121 Stack size = 0x201000 (2101248) bytes
125 In the following run, we see that if a guard size is specified,
126 it is rounded up to the next multiple of the system page size
127 (4096 bytes on x86-32):
131 .RB "$" " ./a.out \-g 4097"
132 Thread attributes object after initializations:
133 Guard size = 4097 bytes
134 Stack address = (nil)
135 Stack size = 0x0 (0) bytes
137 Attributes of created thread:
138 Guard size = 8192 bytes
139 Stack address = 0x40196000 (EOS = 0x40397000)
140 Stack size = 0x201000 (2101248) bytes
145 .\"$ ./a.out \-s 0x8000
146 .\"Thread attributes object after initializations:
147 .\" Guard size = 4096 bytes
148 .\" Stack address = 0xffff8000 (EOS = (nil))
149 .\" Stack size = 0x8000 (32768) bytes
151 .\"Attributes of created thread:
152 .\" Guard size = 4096 bytes
153 .\" Stack address = 0x4001e000 (EOS = 0x40026000)
154 .\" Stack size = 0x8000 (32768) bytes
158 In the last run, the program manually allocates a stack for the thread.
159 In this case, the guard size attribute is ignored.
163 .RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a"
164 Allocated thread stack at 0x804d000
166 Thread attributes object after initializations:
167 Guard size = 4096 bytes
168 Stack address = 0x804d000 (EOS = 0x8055000)
169 Stack size = 0x8000 (32768) bytes
171 Attributes of created thread:
173 Stack address = 0x804d000 (EOS = 0x8055000)
174 Stack size = 0x8000 (32768) bytes
180 #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */
187 #define handle_error_en(en, msg) \e
188 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
191 display_stack_related_attributes(pthread_attr_t *attr, char *prefix)
194 size_t stack_size, guard_size;
197 s = pthread_attr_getguardsize(attr, &guard_size);
199 handle_error_en(s, "pthread_attr_getguardsize");
200 printf("%sGuard size = %zu bytes\en", prefix, guard_size);
202 s = pthread_attr_getstack(attr, &stack_addr, &stack_size);
204 handle_error_en(s, "pthread_attr_getstack");
205 printf("%sStack address = %p", prefix, stack_addr);
207 printf(" (EOS = %p)", (char *) stack_addr + stack_size);
209 printf("%sStack size = %#zx (%zu) bytes\en",
210 prefix, stack_size, stack_size);
214 display_thread_attributes(pthread_t thread, char *prefix)
219 s = pthread_getattr_np(thread, &attr);
221 handle_error_en(s, "pthread_getattr_np");
223 display_stack_related_attributes(&attr, prefix);
225 s = pthread_attr_destroy(&attr);
227 handle_error_en(s, "pthread_attr_destroy");
230 static void * /* Start function for thread we create */
231 thread_start(void *arg)
233 printf("Attributes of created thread:\en");
234 display_thread_attributes(pthread_self(), "\et");
236 exit(EXIT_SUCCESS); /* Terminate all threads */
240 usage(char *pname, char *msg)
244 fprintf(stderr, "Usage: %s [\-s stack\-size [\-a]]"
245 " [\-g guard\-size]\en", pname);
246 fprintf(stderr, "\et\et\-a means program should allocate stack\en");
250 static pthread_attr_t * /* Get thread attributes from command line */
251 get_thread_attributes_from_cl(int argc, char *argv[],
252 pthread_attr_t *attrp)
254 int s, opt, allocate_stack;
255 size_t stack_size, guard_size;
257 pthread_attr_t *ret_attrp = NULL; /* Set to attrp if we initialize
258 a thread attributes object */
263 while ((opt = getopt(argc, argv, "ag:s:")) != \-1) {
265 case \(aqa\(aq: allocate_stack = 1; break;
266 case \(aqg\(aq: guard_size = strtoul(optarg, NULL, 0); break;
267 case \(aqs\(aq: stack_size = strtoul(optarg, NULL, 0); break;
268 default: usage(argv[0], NULL);
272 if (allocate_stack && stack_size == \-1)
273 usage(argv[0], "Specifying \-a without \-s makes no sense\en");
276 usage(argv[0], "Extraneous command\-line arguments\en");
278 if (stack_size >= 0 || guard_size > 0) {
281 s = pthread_attr_init(attrp);
283 handle_error_en(s, "pthread_attr_init");
286 if (stack_size >= 0) {
287 if (!allocate_stack) {
288 s = pthread_attr_setstacksize(attrp, stack_size);
290 handle_error_en(s, "pthread_attr_setstacksize");
292 s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE),
295 handle_error_en(s, "posix_memalign");
296 printf("Allocated thread stack at %p\en\en", stack_addr);
298 s = pthread_attr_setstack(attrp, stack_addr, stack_size);
300 handle_error_en(s, "pthread_attr_setstacksize");
304 if (guard_size >= 0) {
305 s = pthread_attr_setguardsize(attrp, guard_size);
307 handle_error_en(s, "pthread_attr_setstacksize");
314 main(int argc, char *argv[])
319 pthread_attr_t *attrp = NULL; /* Set to &attr if we initialize
320 a thread attributes object */
322 attrp = get_thread_attributes_from_cl(argc, argv, &attr);
325 printf("Thread attributes object after initializations:\en");
326 display_stack_related_attributes(attrp, "\et");
330 s = pthread_create(&thr, attrp, &thread_start, NULL);
332 handle_error_en(s, "pthread_create");
335 s = pthread_attr_destroy(attrp);
337 handle_error_en(s, "pthread_attr_destroy");
340 pause(); /* Terminates when other thread calls exit() */
346 .BR pthread_attr_getaffinity_np (3),
347 .BR pthread_attr_getdetachstate (3),
348 .BR pthread_attr_getguardsize (3),
349 .BR pthread_attr_getinheritsched (3),
350 .BR pthread_attr_getschedparam (3),
351 .BR pthread_attr_getschedpolicy (3),
352 .BR pthread_attr_getscope (3),
353 .BR pthread_attr_getstack (3),
354 .BR pthread_attr_getstackaddr (3),
355 .BR pthread_attr_getstacksize (3),
356 .BR pthread_attr_init (3),
357 .BR pthread_create (3),