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 2019-03-06 "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.
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).
80 For an explanation of the terms used in this section, see
87 Interface Attribute Value
89 .BR pthread_attr_init (),
90 .BR pthread_attr_destroy ()
91 T} Thread safety MT-Safe
95 POSIX.1-2001, POSIX.1-2008.
99 type should be treated as opaque:
100 any access to the object other than via pthreads functions
101 is nonportable and produces undefined results.
103 The program below optionally makes use of
104 .BR pthread_attr_init ()
105 and various related functions to initialize a thread attributes
106 object that is used to create a single thread.
107 Once created, the thread uses the
108 .BR pthread_getattr_np (3)
109 function (a nonstandard GNU extension) to retrieve the thread's
110 attributes, and then displays those attributes.
112 If the program is run with no command-line argument,
113 then it passes NULL as the
116 .BR pthread_create (3),
117 so that the thread is created with default attributes.
118 Running the program on Linux/x86-32 with the NPTL threading implementation,
119 we see the following:
123 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
124 .RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB"
128 Detach state = PTHREAD_CREATE_JOINABLE
129 Scope = PTHREAD_SCOPE_SYSTEM
130 Inherit scheduler = PTHREAD_INHERIT_SCHED
131 Scheduling policy = SCHED_OTHER
132 Scheduling priority = 0
133 Guard size = 4096 bytes
134 Stack address = 0x40196000
135 Stack size = 0x201000 bytes
139 When we supply a stack size as a command-line argument,
140 the program initializes a thread attributes object,
141 sets various attributes in that object,
142 and passes a pointer to the object in the call to
143 .BR pthread_create (3).
144 Running the program on Linux/x86-32 with the NPTL threading implementation,
145 we see the following:
149 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
150 .RB "$" " ./a.out 0x3000000"
151 posix_memalign() allocated at 0x40197000
153 Detach state = PTHREAD_CREATE_DETACHED
154 Scope = PTHREAD_SCOPE_SYSTEM
155 Inherit scheduler = PTHREAD_EXPLICIT_SCHED
156 Scheduling policy = SCHED_OTHER
157 Scheduling priority = 0
159 Stack address = 0x40197000
160 Stack size = 0x3000000 bytes
166 #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */
173 #define handle_error_en(en, msg) \e
174 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
177 display_pthread_attr(pthread_attr_t *attr, char *prefix)
182 struct sched_param sp;
184 s = pthread_attr_getdetachstate(attr, &i);
186 handle_error_en(s, "pthread_attr_getdetachstate");
187 printf("%sDetach state = %s\en", prefix,
188 (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
189 (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
192 s = pthread_attr_getscope(attr, &i);
194 handle_error_en(s, "pthread_attr_getscope");
195 printf("%sScope = %s\en", prefix,
196 (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" :
197 (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
200 s = pthread_attr_getinheritsched(attr, &i);
202 handle_error_en(s, "pthread_attr_getinheritsched");
203 printf("%sInherit scheduler = %s\en", prefix,
204 (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" :
205 (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
208 s = pthread_attr_getschedpolicy(attr, &i);
210 handle_error_en(s, "pthread_attr_getschedpolicy");
211 printf("%sScheduling policy = %s\en", prefix,
212 (i == SCHED_OTHER) ? "SCHED_OTHER" :
213 (i == SCHED_FIFO) ? "SCHED_FIFO" :
214 (i == SCHED_RR) ? "SCHED_RR" :
217 s = pthread_attr_getschedparam(attr, &sp);
219 handle_error_en(s, "pthread_attr_getschedparam");
220 printf("%sScheduling priority = %d\en", prefix, sp.sched_priority);
222 s = pthread_attr_getguardsize(attr, &v);
224 handle_error_en(s, "pthread_attr_getguardsize");
225 printf("%sGuard size = %zu bytes\en", prefix, v);
227 s = pthread_attr_getstack(attr, &stkaddr, &v);
229 handle_error_en(s, "pthread_attr_getstack");
230 printf("%sStack address = %p\en", prefix, stkaddr);
231 printf("%sStack size = 0x%zx bytes\en", prefix, v);
235 thread_start(void *arg)
238 pthread_attr_t gattr;
240 /* pthread_getattr_np() is a non\-standard GNU extension that
241 retrieves the attributes of the thread specified in its
244 s = pthread_getattr_np(pthread_self(), &gattr);
246 handle_error_en(s, "pthread_getattr_np");
248 printf("Thread attributes:\en");
249 display_pthread_attr(&gattr, "\et");
251 exit(EXIT_SUCCESS); /* Terminate all threads */
255 main(int argc, char *argv[])
259 pthread_attr_t *attrp; /* NULL or &attr */
264 /* If a command\-line argument was supplied, use it to set the
265 stack\-size attribute and set a few other thread attributes,
266 and set attrp pointing to thread attributes object */
274 s = pthread_attr_init(&attr);
276 handle_error_en(s, "pthread_attr_init");
278 s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
280 handle_error_en(s, "pthread_attr_setdetachstate");
282 s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
284 handle_error_en(s, "pthread_attr_setinheritsched");
286 stack_size = strtoul(argv[1], NULL, 0);
288 s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
290 handle_error_en(s, "posix_memalign");
292 printf("posix_memalign() allocated at %p\en", sp);
294 s = pthread_attr_setstack(&attr, sp, stack_size);
296 handle_error_en(s, "pthread_attr_setstack");
299 s = pthread_create(&thr, attrp, &thread_start, NULL);
301 handle_error_en(s, "pthread_create");
304 s = pthread_attr_destroy(attrp);
306 handle_error_en(s, "pthread_attr_destroy");
309 pause(); /* Terminates when other thread calls exit() */
315 .BR pthread_attr_setaffinity_np (3),
316 .BR pthread_attr_setdetachstate (3),
317 .BR pthread_attr_setguardsize (3),
318 .BR pthread_attr_setinheritsched (3),
319 .BR pthread_attr_setschedparam (3),
320 .BR pthread_attr_setschedpolicy (3),
321 .BR pthread_attr_setscope (3),
322 .BR pthread_attr_setstack (3),
323 .BR pthread_attr_setstackaddr (3),
324 .BR pthread_attr_setstacksize (3),
325 .BR pthread_create (3),
326 .BR pthread_getattr_np (3),
327 .BR pthread_setattr_default_np (3),