1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH PTHREAD_GETATTR_NP 3 2010-09-10 "Linux" "Linux Programmer's Manual"
28 pthread_getattr_np \- get attributes of created thread
31 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
32 .B #include <pthread.h>
34 .BI "int pthread_getattr_np(pthread_t " thread ", pthread_attr_t *" attr );
36 Compile and link with \fI\-pthread\fP.
40 .BR pthread_getattr_np ()
41 function initializes the thread attributes object referred to by
43 so that it contains actual attribute values describing the running thread
46 The returned attribute values may differ from
47 the corresponding attribute values passed in the
49 object that was used to create the thread using
50 .BR pthread_create (3).
51 In particular, the following attributes may differ:
53 the detach state, since a joinable thread may have detached itself
57 which the implementation may align to a suitable boundary.
60 which the implementation may round upward to a multiple of the page size,
61 or ignore (i.e., treat as 0),
62 if the application is allocating its own stack.
64 Furthermore, if the stack address attribute was not set
65 in the thread attributes object used to create the thread,
66 then the returned thread attributes object will report the actual
67 stack address that the implementation selected for the thread.
69 When the thread attributes object returned by
70 .BR pthread_getattr_np ()
71 is no longer required, it should be destroyed using
72 .BR pthread_attr_destroy (3).
74 On success, this function returns 0;
75 on error, it returns a nonzero error number.
79 .\" Can happen (but unlikely) while trying to allocate memory for cpuset
84 refers to the main thread, then
85 .BR pthread_getattr_np ()
86 can fail because of errors from various underlying calls:
95 resource limit is not supported.
97 This function is available in glibc since version 2.2.3.
99 This function is a nonstandard GNU extension;
100 hence the suffix "_np" (nonportable) in the name.
102 The program below demonstrates the use of
103 .BR pthread_getattr_np ().
104 The program creates a thread that then uses
105 .BR pthread_getattr_np ()
106 to retrieve and display its guard size, stack address,
107 and stack size attributes.
108 Command-line arguments can be used to set these attributes
109 to values other than the default when creating the thread.
110 The shell sessions below demonstrate the use of the program.
112 In the first run, on an x86-32 system,
113 a thread is created using default attributes:
117 .RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2MB"
120 Attributes of created thread:
121 Guard size = 4096 bytes
122 Stack address = 0x40196000 (EOS = 0x40397000)
123 Stack size = 0x201000 (2101248) bytes
127 In the following run, we see that if a guard size is specified,
128 it is rounded up to the next multiple of the system page size
129 (4096 bytes on x86-32):
133 .RB "$" " ./a.out \-g 4097"
134 Thread attributes object after initializations:
135 Guard size = 4097 bytes
136 Stack address = (nil)
137 Stack size = 0x0 (0) bytes
139 Attributes of created thread:
140 Guard size = 8192 bytes
141 Stack address = 0x40196000 (EOS = 0x40397000)
142 Stack size = 0x201000 (2101248) bytes
147 .\"$ ./a.out \-s 0x8000
148 .\"Thread attributes object after initializations:
149 .\" Guard size = 4096 bytes
150 .\" Stack address = 0xffff8000 (EOS = (nil))
151 .\" Stack size = 0x8000 (32768) bytes
153 .\"Attributes of created thread:
154 .\" Guard size = 4096 bytes
155 .\" Stack address = 0x4001e000 (EOS = 0x40026000)
156 .\" Stack size = 0x8000 (32768) bytes
160 In the last run, the program manually allocates a stack for the thread.
161 In this case, the guard size attribute is ignored.
165 .RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a"
166 Allocated thread stack at 0x804d000
168 Thread attributes object after initializations:
169 Guard size = 4096 bytes
170 Stack address = 0x804d000 (EOS = 0x8055000)
171 Stack size = 0x8000 (32768) bytes
173 Attributes of created thread:
175 Stack address = 0x804d000 (EOS = 0x8055000)
176 Stack size = 0x8000 (32768) bytes
182 #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */
189 #define handle_error_en(en, msg) \\
190 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
193 display_stack_related_attributes(pthread_attr_t *attr, char *prefix)
196 size_t stack_size, guard_size;
199 s = pthread_attr_getguardsize(attr, &guard_size);
201 handle_error_en(s, "pthread_attr_getguardsize");
202 printf("%sGuard size = %d bytes\\n", prefix, guard_size);
204 s = pthread_attr_getstack(attr, &stack_addr, &stack_size);
206 handle_error_en(s, "pthread_attr_getstack");
207 printf("%sStack address = %p", prefix, stack_addr);
209 printf(" (EOS = %p)", (char *) stack_addr + stack_size);
211 printf("%sStack size = 0x%x (%d) bytes\\n",
212 prefix, stack_size, stack_size);
216 display_thread_attributes(pthread_t thread, char *prefix)
221 s = pthread_getattr_np(thread, &attr);
223 handle_error_en(s, "pthread_getattr_np");
225 display_stack_related_attributes(&attr, prefix);
227 s = pthread_attr_destroy(&attr);
229 handle_error_en(s, "pthread_attr_destroy");
232 static void * /* Start function for thread we create */
233 thread_start(void *arg)
235 printf("Attributes of created thread:\\n");
236 display_thread_attributes(pthread_self(), "\\t");
238 exit(EXIT_SUCCESS); /* Terminate all threads */
242 usage(char *pname, char *msg)
246 fprintf(stderr, "Usage: %s [\-s stack\-size [\-a]]"
247 " [\-g guard\-size]\\n", pname);
248 fprintf(stderr, "\\t\\t\-a means program should allocate stack\\n");
252 static pthread_attr_t * /* Get thread attributes from command line */
253 get_thread_attributes_from_cl(int argc, char *argv[],
254 pthread_attr_t *attrp)
256 int s, opt, allocate_stack;
257 long stack_size, guard_size;
259 pthread_attr_t *ret_attrp = NULL; /* Set to attrp if we initialize
260 a thread attributes object */
265 while ((opt = getopt(argc, argv, "ag:s:")) != \-1) {
267 case \(aqa\(aq: allocate_stack = 1; break;
268 case \(aqg\(aq: guard_size = strtoul(optarg, NULL, 0); break;
269 case \(aqs\(aq: stack_size = strtoul(optarg, NULL, 0); break;
270 default: usage(argv[0], NULL);
274 if (allocate_stack && stack_size == \-1)
275 usage(argv[0], "Specifying \-a without \-s makes no sense\\n");
278 usage(argv[0], "Extraneous command\-line arguments\\n");
280 if (stack_size >= 0 || guard_size > 0) {
283 s = pthread_attr_init(attrp);
285 handle_error_en(s, "pthread_attr_init");
288 if (stack_size >= 0) {
289 if (!allocate_stack) {
290 s = pthread_attr_setstacksize(attrp, stack_size);
292 handle_error_en(s, "pthread_attr_setstacksize");
294 s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE),
297 handle_error_en(s, "posix_memalign");
298 printf("Allocated thread stack at %p\\n\\n", stack_addr);
300 s = pthread_attr_setstack(attrp, stack_addr, stack_size);
302 handle_error_en(s, "pthread_attr_setstacksize");
306 if (guard_size >= 0) {
307 s = pthread_attr_setguardsize(attrp, guard_size);
309 handle_error_en(s, "pthread_attr_setstacksize");
316 main(int argc, char *argv[])
321 pthread_attr_t *attrp = NULL; /* Set to &attr if we initialize
322 a thread attributes object */
324 attrp = get_thread_attributes_from_cl(argc, argv, &attr);
327 printf("Thread attributes object after initializations:\\n");
328 display_stack_related_attributes(attrp, "\\t");
332 s = pthread_create(&thr, attrp, &thread_start, NULL);
334 handle_error_en(s, "pthread_create");
337 s = pthread_attr_destroy(attrp);
339 handle_error_en(s, "pthread_attr_destroy");
342 pause(); /* Terminates when other thread calls exit() */
348 .BR pthread_attr_getaffinity_np (3),
349 .BR pthread_attr_getdetachstate (3),
350 .BR pthread_attr_getguardsize (3),
351 .BR pthread_attr_getinheritsched (3),
352 .BR pthread_attr_getschedparam (3),
353 .BR pthread_attr_getschedpolicy (3),
354 .BR pthread_attr_getscope (3),
355 .BR pthread_attr_getstack (3),
356 .BR pthread_attr_getstackaddr (3),
357 .BR pthread_attr_getstacksize (3),
358 .BR pthread_attr_init (3),
359 .BR pthread_create (3),