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 (date) "Linux man-pages (unreleased)"
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
179 .\" SRC BEGIN (pthread_getattr_np.c)
181 #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */
190 display_stack_related_attributes(pthread_attr_t *attr, char *prefix)
193 size_t stack_size, guard_size;
196 s = pthread_attr_getguardsize(attr, &guard_size);
198 errc(EXIT_FAILURE, s, "pthread_attr_getguardsize");
199 printf("%sGuard size = %zu bytes\en", prefix, guard_size);
201 s = pthread_attr_getstack(attr, &stack_addr, &stack_size);
203 errc(EXIT_FAILURE, s, "pthread_attr_getstack");
204 printf("%sStack address = %p", prefix, stack_addr);
206 printf(" (EOS = %p)", (char *) stack_addr + stack_size);
208 printf("%sStack size = %#zx (%zu) bytes\en",
209 prefix, stack_size, stack_size);
213 display_thread_attributes(pthread_t thread, char *prefix)
218 s = pthread_getattr_np(thread, &attr);
220 errc(EXIT_FAILURE, s, "pthread_getattr_np");
222 display_stack_related_attributes(&attr, prefix);
224 s = pthread_attr_destroy(&attr);
226 errc(EXIT_FAILURE, s, "pthread_attr_destroy");
229 static void * /* Start function for thread we create */
230 thread_start(void *arg)
232 printf("Attributes of created thread:\en");
233 display_thread_attributes(pthread_self(), "\et");
235 exit(EXIT_SUCCESS); /* Terminate all threads */
239 usage(char *pname, char *msg)
243 fprintf(stderr, "Usage: %s [\-s stack\-size [\-a]]"
244 " [\-g guard\-size]\en", pname);
245 fprintf(stderr, "\et\et\-a means program should allocate stack\en");
249 static pthread_attr_t * /* Get thread attributes from command line */
250 get_thread_attributes_from_cl(int argc, char *argv[],
251 pthread_attr_t *attrp)
253 int s, opt, allocate_stack;
254 size_t stack_size, guard_size;
256 pthread_attr_t *ret_attrp = NULL; /* Set to attrp if we initialize
257 a thread attributes object */
262 while ((opt = getopt(argc, argv, "ag:s:")) != \-1) {
264 case \(aqa\(aq: allocate_stack = 1; break;
265 case \(aqg\(aq: guard_size = strtoul(optarg, NULL, 0); break;
266 case \(aqs\(aq: stack_size = strtoul(optarg, NULL, 0); break;
267 default: usage(argv[0], NULL);
271 if (allocate_stack && stack_size == \-1)
272 usage(argv[0], "Specifying \-a without \-s makes no sense\en");
275 usage(argv[0], "Extraneous command\-line arguments\en");
277 if (stack_size >= 0 || guard_size > 0) {
280 s = pthread_attr_init(attrp);
282 errc(EXIT_FAILURE, s, "pthread_attr_init");
285 if (stack_size >= 0) {
286 if (!allocate_stack) {
287 s = pthread_attr_setstacksize(attrp, stack_size);
289 errc(EXIT_FAILURE, s, "pthread_attr_setstacksize");
291 s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE),
294 errc(EXIT_FAILURE, s, "posix_memalign");
295 printf("Allocated thread stack at %p\en\en", stack_addr);
297 s = pthread_attr_setstack(attrp, stack_addr, stack_size);
299 errc(EXIT_FAILURE, s, "pthread_attr_setstacksize");
303 if (guard_size >= 0) {
304 s = pthread_attr_setguardsize(attrp, guard_size);
306 errc(EXIT_FAILURE, s, "pthread_attr_setstacksize");
313 main(int argc, char *argv[])
318 pthread_attr_t *attrp = NULL; /* Set to &attr if we initialize
319 a thread attributes object */
321 attrp = get_thread_attributes_from_cl(argc, argv, &attr);
324 printf("Thread attributes object after initializations:\en");
325 display_stack_related_attributes(attrp, "\et");
329 s = pthread_create(&thr, attrp, &thread_start, NULL);
331 errc(EXIT_FAILURE, s, "pthread_create");
334 s = pthread_attr_destroy(attrp);
336 errc(EXIT_FAILURE, s, "pthread_attr_destroy");
339 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),