1PTHREAD_ATTR_INIT(3) Linux Programmer's Manual PTHREAD_ATTR_INIT(3)
2
6 pthread_attr_init, pthread_attr_destroy - initialize and destroy thread
7 attributes object
8
10 #include <pthread.h>
11 int pthread_attr_init(pthread_attr_t *attr);
13 int pthread_attr_destroy(pthread_attr_t *attr);
14 Compile and link with -pthread.
16
18 The pthread_attr_init() function initializes the thread attributes
19 object pointed to by attr with default attribute values. After this
20 call, individual attributes of the object can be set using various
21 related functions (listed under SEE ALSO), and then the object can be
22 used in one or more pthread_create(3) calls that create threads.
23 Calling pthread_attr_init() on a thread attributes object that has
25 already been initialized results in undefined behavior.
26 When a thread attributes object is no longer required, it should be
28 destroyed using the pthread_attr_destroy() function. Destroying a
29 thread attributes object has no effect on threads that were created
30 using that object.
31 Once a thread attributes object has been destroyed, it can be reini‐
33 tialized using pthread_attr_init(). Any other use of a destroyed
34 thread attributes object has undefined results.
35
37 On success, these functions return 0; on error, they return a nonzero
38 error number.
39
41 POSIX.1 documents an ENOMEM error for pthread_attr_init(); on Linux
42 these functions always succeed (but portable and future-proof applica‐
43 tions should nevertheless handle a possible error return).
44
46 For an explanation of the terms used in this section, see
47 attributes(7).
48 ┌───────────────────────┬───────────────┬─────────┐
50 │Interface │ Attribute │ Value │
51 ├───────────────────────┼───────────────┼─────────┤
52 │pthread_attr_init(), │ Thread safety │ MT-Safe │
53 │pthread_attr_destroy() │ │ │
54 └───────────────────────┴───────────────┴─────────┘
56 POSIX.1-2001, POSIX.1-2008.
57
59 The pthread_attr_t type should be treated as opaque: any access to the
60 object other than via pthreads functions is nonportable and produces
61 undefined results.
62
64 The program below optionally makes use of pthread_attr_init() and vari‐
65 ous related functions to initialize a thread attributes object that is
66 used to create a single thread. Once created, the thread uses the
67 pthread_getattr_np(3) function (a nonstandard GNU extension) to
68 retrieve the thread's attributes, and then displays those attributes.
69 If the program is run with no command-line argument, then it passes
71 NULL as the attr argument of pthread_create(3), so that the thread is
72 created with default attributes. Running the program on Linux/x86-32
73 with the NPTL threading implementation, we see the following:
74 $ ulimit -s # No stack limit ==> default stack size is 2 MB
76 unlimited
77 $ ./a.out
78 Thread attributes:
79 Detach state = PTHREAD_CREATE_JOINABLE
80 Scope = PTHREAD_SCOPE_SYSTEM
81 Inherit scheduler = PTHREAD_INHERIT_SCHED
82 Scheduling policy = SCHED_OTHER
83 Scheduling priority = 0
84 Guard size = 4096 bytes
85 Stack address = 0x40196000
86 Stack size = 0x201000 bytes
87 When we supply a stack size as a command-line argument, the program
89 initializes a thread attributes object, sets various attributes in that
90 object, and passes a pointer to the object in the call to pthread_cre‐
91 ate(3). Running the program on Linux/x86-32 with the NPTL threading
92 implementation, we see the following:
93 $ ./a.out 0x3000000
95 posix_memalign() allocated at 0x40197000
96 Thread attributes:
97 Detach state = PTHREAD_CREATE_DETACHED
98 Scope = PTHREAD_SCOPE_SYSTEM
99 Inherit scheduler = PTHREAD_EXPLICIT_SCHED
100 Scheduling policy = SCHED_OTHER
101 Scheduling priority = 0
102 Guard size = 0 bytes
103 Stack address = 0x40197000
104 Stack size = 0x3000000 bytes
105 Program source
107 #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */
109 #include <pthread.h>
110 #include <stdio.h>
111 #include <stdlib.h>
112 #include <unistd.h>
113 #include <errno.h>
114 #define handle_error_en(en, msg) \
116 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
117 static void
119 display_pthread_attr(pthread_attr_t *attr, char *prefix)
120 {
121 int s, i;
122 size_t v;
123 void *stkaddr;
124 struct sched_param sp;
125 s = pthread_attr_getdetachstate(attr, &i);
127 if (s != 0)
128 handle_error_en(s, "pthread_attr_getdetachstate");
129 printf("%sDetach state = %s\n", prefix,
130 (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
131 (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
132 "???");
133 s = pthread_attr_getscope(attr, &i);
135 if (s != 0)
136 handle_error_en(s, "pthread_attr_getscope");
137 printf("%sScope = %s\n", prefix,
138 (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" :
139 (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
140 "???");
141 s = pthread_attr_getinheritsched(attr, &i);
143 if (s != 0)
144 handle_error_en(s, "pthread_attr_getinheritsched");
145 printf("%sInherit scheduler = %s\n", prefix,
146 (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" :
147 (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
148 "???");
149 s = pthread_attr_getschedpolicy(attr, &i);
151 if (s != 0)
152 handle_error_en(s, "pthread_attr_getschedpolicy");
153 printf("%sScheduling policy = %s\n", prefix,
154 (i == SCHED_OTHER) ? "SCHED_OTHER" :
155 (i == SCHED_FIFO) ? "SCHED_FIFO" :
156 (i == SCHED_RR) ? "SCHED_RR" :
157 "???");
158 s = pthread_attr_getschedparam(attr, &sp);
160 if (s != 0)
161 handle_error_en(s, "pthread_attr_getschedparam");
162 printf("%sScheduling priority = %d\n", prefix, sp.sched_priority);
163 s = pthread_attr_getguardsize(attr, &v);
165 if (s != 0)
166 handle_error_en(s, "pthread_attr_getguardsize");
167 printf("%sGuard size = %d bytes\n", prefix, v);
168 s = pthread_attr_getstack(attr, &stkaddr, &v);
170 if (s != 0)
171 handle_error_en(s, "pthread_attr_getstack");
172 printf("%sStack address = %p\n", prefix, stkaddr);
173 printf("%sStack size = 0x%zx bytes\n", prefix, v);
174 }
175 static void *
177 thread_start(void *arg)
178 {
179 int s;
180 pthread_attr_t gattr;
181 /* pthread_getattr_np() is a non-standard GNU extension that
183 retrieves the attributes of the thread specified in its
184 first argument */
185 s = pthread_getattr_np(pthread_self(), &gattr);
187 if (s != 0)
188 handle_error_en(s, "pthread_getattr_np");
189 printf("Thread attributes:\n");
191 display_pthread_attr(&gattr, "\t");
192 exit(EXIT_SUCCESS); /* Terminate all threads */
194 }
195 int
197 main(int argc, char *argv[])
198 {
199 pthread_t thr;
200 pthread_attr_t attr;
201 pthread_attr_t *attrp; /* NULL or &attr */
202 int s;
203 attrp = NULL;
205 /* If a command-line argument was supplied, use it to set the
207 stack-size attribute and set a few other thread attributes,
208 and set attrp pointing to thread attributes object */
209 if (argc > 1) {
211 int stack_size;
212 void *sp;
213 attrp = &attr;
215 s = pthread_attr_init(&attr);
217 if (s != 0)
218 handle_error_en(s, "pthread_attr_init");
219 s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
221 if (s != 0)
222 handle_error_en(s, "pthread_attr_setdetachstate");
223 s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
225 if (s != 0)
226 handle_error_en(s, "pthread_attr_setinheritsched");
227 stack_size = strtoul(argv[1], NULL, 0);
229 s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
231 if (s != 0)
232 handle_error_en(s, "posix_memalign");
233 printf("posix_memalign() allocated at %p\n", sp);
235 s = pthread_attr_setstack(&attr, sp, stack_size);
237 if (s != 0)
238 handle_error_en(s, "pthread_attr_setstack");
239 }
240 s = pthread_create(&thr, attrp, &thread_start, NULL);
242 if (s != 0)
243 handle_error_en(s, "pthread_create");
244 if (attrp != NULL) {
246 s = pthread_attr_destroy(attrp);
247 if (s != 0)
248 handle_error_en(s, "pthread_attr_destroy");
249 }
250 pause(); /* Terminates when other thread calls exit() */
252 }
253
255 pthread_attr_setaffinity_np(3), pthread_attr_setdetachstate(3),
256 pthread_attr_setguardsize(3), pthread_attr_setinheritsched(3),
257 pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3),
258 pthread_attr_setscope(3), pthread_attr_setstack(3),
259 pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3),
260 pthread_create(3), pthread_getattr_np(3),
261 pthread_setattr_default_np(3), pthreads(7)
262
264 This page is part of release 4.16 of the Linux man-pages project. A
265 description of the project, information about reporting bugs, and the
266 latest version of this page, can be found at
267 https://www.kernel.org/doc/man-pages/.
268Linux 2017-09-15 PTHREAD_ATTR_INIT(3)