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_ATTR_INIT 3 2008-11-11 "Linux" "Linux Programmer's Manual"
28 pthread_attr_init, pthread_attr_destroy \- initialize and destroy
29 thread attributes object
32 .B #include <pthread.h>
34 .BI "int pthread_attr_init(pthread_attr_t *" attr );
35 .BI "int pthread_attr_destroy(pthread_attr_t *" attr );
37 Compile and link with \fI\-pthread\fP.
41 .BR pthread_attr_init ()
42 function initializes the thread attributes object pointed to by
44 with default attribute values.
45 After this call, individual attributes of the object can be set
46 using various related functions (listed under SEE ALSO),
47 and then the object can be used in one or more
48 .BR pthread_create (3)
49 calls that create threads.
52 .BR pthread_attr_init ()
53 on a thread attributes object that has already been initialized
54 results in undefined behavior.
56 When a thread attributes object is no longer required,
57 it should be destroyed using the
58 .BR pthread_attr_destroy ()
60 Destroying a thread attributes object has no effect
61 on threads that were created using that object.
63 Once a thread attributes object has been destroyed,
64 it can be reinitialized using
65 .BR pthread_attr_init ().
66 Any other use of a destroyed thread attributes object
67 has undefined results.
69 On success, these functions return 0;
70 on error, they return a nonzero error number.
72 POSIX.1-2001 documents an
75 .BR pthread_attr_init ();
76 on Linux these functions always succeed
77 (but portable and future-proof applications should nevertheless
78 handle a possible error return).
84 type should be treated as opaque:
85 any access to the object other than via pthreads functions
86 is nonportable and produces undefined results.
88 The program below optionally makes use of
89 .BR pthread_attr_init ()
90 and various related functions to initialize a thread attributes
91 object that is used to create a single thread.
92 Once created, the thread uses the
93 .BR pthread_getattr_np (3)
94 function (a nonstandard GNU extension) to retrieve the thread's
95 attributes, and then displays those attributes.
97 If the program is run with no command-line argument,
98 then it passes NULL as the
101 .BR pthread_create (3),
102 so that the thread is created with default attributes.
103 Running the program on Linux/x86-32 with the NPTL threading implementation,
104 we see the following:
108 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
109 .RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2MB"
113 Detach state = PTHREAD_CREATE_JOINABLE
114 Scope = PTHREAD_SCOPE_SYSTEM
115 Inherit scheduler = PTHREAD_INHERIT_SCHED
116 Scheduling policy = SCHED_OTHER
117 Scheduling priority = 0
118 Guard size = 4096 bytes
119 Stack address = 0x40196000
120 Stack size = 0x201000 bytes
124 When we supply a stack size as a command-line argument,
125 the program initializes a thread attributes object,
126 sets various attributes in that object,
127 and passes a pointer to the object in the call to
128 .BR pthread_create (3).
129 Running the program on Linux/x86-32 with the NPTL threading implementation,
130 we see the following:
134 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
135 .RB "$" " ./a.out 0x3000000"
136 posix_memalign() allocated at 0x40197000
138 Detach state = PTHREAD_CREATE_DETACHED
139 Scope = PTHREAD_SCOPE_SYSTEM
140 Inherit scheduler = PTHREAD_EXPLICIT_SCHED
141 Scheduling policy = SCHED_OTHER
142 Scheduling priority = 0
144 Stack address = 0x40197000
145 Stack size = 0x3000000 bytes
151 #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */
158 #define handle_error_en(en, msg) \\
159 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
162 display_pthread_attr(pthread_attr_t *attr, char *prefix)
167 struct sched_param sp;
169 s = pthread_attr_getdetachstate(attr, &i);
171 handle_error_en(s, "pthread_attr_getdetachstate");
172 printf("%sDetach state = %s\\n", prefix,
173 (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
174 (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
177 s = pthread_attr_getscope(attr, &i);
179 handle_error_en(s, "pthread_attr_getscope");
180 printf("%sScope = %s\\n", prefix,
181 (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" :
182 (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
185 s = pthread_attr_getinheritsched(attr, &i);
187 handle_error_en(s, "pthread_attr_getinheritsched");
188 printf("%sInherit scheduler = %s\\n", prefix,
189 (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" :
190 (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
193 s = pthread_attr_getschedpolicy(attr, &i);
195 handle_error_en(s, "pthread_attr_getschedpolicy");
196 printf("%sScheduling policy = %s\\n", prefix,
197 (i == SCHED_OTHER) ? "SCHED_OTHER" :
198 (i == SCHED_FIFO) ? "SCHED_FIFO" :
199 (i == SCHED_RR) ? "SCHED_RR" :
202 s = pthread_attr_getschedparam(attr, &sp);
204 handle_error_en(s, "pthread_attr_getschedparam");
205 printf("%sScheduling priority = %d\\n", prefix, sp.sched_priority);
207 s = pthread_attr_getguardsize(attr, &v);
209 handle_error_en(s, "pthread_attr_getguardsize");
210 printf("%sGuard size = %d bytes\\n", prefix, v);
212 s = pthread_attr_getstack(attr, &stkaddr, &v);
214 handle_error_en(s, "pthread_attr_getstack");
215 printf("%sStack address = %p\\n", prefix, stkaddr);
216 printf("%sStack size = 0x%x bytes\\n", prefix, v);
220 thread_start(void *arg)
223 pthread_attr_t gattr;
225 /* pthread_getattr_np() is a non\-standard GNU extension that
226 retrieves the attributes of the thread specified in its
229 s = pthread_getattr_np(pthread_self(), &gattr);
231 handle_error_en(s, "pthread_getattr_np");
233 printf("Thread attributes:\\n");
234 display_pthread_attr(&gattr, "\\t");
236 exit(EXIT_SUCCESS); /* Terminate all threads */
240 main(int argc, char *argv[])
244 pthread_attr_t *attrp; /* NULL or &attr */
249 /* If a command\-line argument was supplied, use it to set the
250 stack\-size attribute and set a few other thread attributes,
251 and set attrp pointing to thread attributes object */
259 s = pthread_attr_init(&attr);
261 handle_error_en(s, "pthread_attr_init");
263 s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
265 handle_error_en(s, "pthread_attr_setdetachstate");
267 s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
269 handle_error_en(s, "pthread_attr_setinheritsched");
271 stack_size = strtoul(argv[1], NULL, 0);
273 s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
275 handle_error_en(s, "posix_memalign");
277 printf("posix_memalign() allocated at %p\\n", sp);
279 s = pthread_attr_setstack(&attr, sp, stack_size);
281 handle_error_en(s, "pthread_attr_setstack");
284 s = pthread_create(&thr, attrp, &thread_start, NULL);
286 handle_error_en(s, "pthread_create");
289 s = pthread_attr_destroy(attrp);
291 handle_error_en(s, "pthread_attr_destroy");
294 pause(); /* Terminates when other thread calls exit() */
300 .BR pthread_attr_setaffinity_np (3),
301 .BR pthread_attr_setdetachstate (3),
302 .BR pthread_attr_setguardsize (3),
303 .BR pthread_attr_setinheritsched (3),
304 .BR pthread_attr_setschedparam (3),
305 .BR pthread_attr_setschedpolicy (3),
306 .BR pthread_attr_setscope (3),
307 .BR pthread_attr_setstack (3),
308 .BR pthread_attr_setstackaddr (3),
309 .BR pthread_attr_setstacksize (3),
310 .BR pthread_create (3),
311 .BR pthread_getattr_np (3),
314 This page is part of release 3.78 of the Linux
317 A description of the project,
318 information about reporting bugs,
319 and the latest version of this page,
321 \%http://www.kernel.org/doc/man\-pages/.