]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
7896a155 MK |
2 | .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
3 | .\" <mtk.manpages@gmail.com> | |
4 | .\" | |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
7896a155 | 6 | .\" |
4c1c5274 | 7 | .TH pthread_attr_init 3 (date) "Linux man-pages (unreleased)" |
7896a155 MK |
8 | .SH NAME |
9 | pthread_attr_init, pthread_attr_destroy \- initialize and destroy | |
10 | thread attributes object | |
6748db1a AC |
11 | .SH LIBRARY |
12 | POSIX threads library | |
8fc3b2cf | 13 | .RI ( libpthread ", " \-lpthread ) |
7896a155 MK |
14 | .SH SYNOPSIS |
15 | .nf | |
16 | .B #include <pthread.h> | |
c6d039a3 | 17 | .P |
7896a155 MK |
18 | .BI "int pthread_attr_init(pthread_attr_t *" attr ); |
19 | .BI "int pthread_attr_destroy(pthread_attr_t *" attr ); | |
6030f2d8 | 20 | .fi |
7896a155 MK |
21 | .SH DESCRIPTION |
22 | The | |
23 | .BR pthread_attr_init () | |
24 | function initializes the thread attributes object pointed to by | |
1ae6b2c7 | 25 | .I attr |
7896a155 MK |
26 | with default attribute values. |
27 | After this call, individual attributes of the object can be set | |
28 | using various related functions (listed under SEE ALSO), | |
29 | and then the object can be used in one or more | |
30 | .BR pthread_create (3) | |
31 | calls that create threads. | |
c6d039a3 | 32 | .P |
c5571b61 | 33 | Calling |
7896a155 MK |
34 | .BR pthread_attr_init () |
35 | on a thread attributes object that has already been initialized | |
36 | results in undefined behavior. | |
c6d039a3 | 37 | .P |
7896a155 MK |
38 | When a thread attributes object is no longer required, |
39 | it should be destroyed using the | |
40 | .BR pthread_attr_destroy () | |
41 | function. | |
42 | Destroying a thread attributes object has no effect | |
43 | on threads that were created using that object. | |
c6d039a3 | 44 | .P |
7896a155 MK |
45 | Once a thread attributes object has been destroyed, |
46 | it can be reinitialized using | |
47 | .BR pthread_attr_init (). | |
48 | Any other use of a destroyed thread attributes object | |
49 | has undefined results. | |
50 | .SH RETURN VALUE | |
51 | On success, these functions return 0; | |
c7094399 | 52 | on error, they return a nonzero error number. |
7896a155 | 53 | .SH ERRORS |
8bf49a72 | 54 | POSIX.1 documents an |
7896a155 MK |
55 | .B ENOMEM |
56 | error for | |
57 | .BR pthread_attr_init (); | |
58 | on Linux these functions always succeed | |
59 | (but portable and future-proof applications should nevertheless | |
60 | handle a possible error return). | |
cdb9dd9e ZL |
61 | .SH ATTRIBUTES |
62 | For an explanation of the terms used in this section, see | |
63 | .BR attributes (7). | |
64 | .TS | |
65 | allbox; | |
c466875e | 66 | lbx lb lb |
cdb9dd9e ZL |
67 | l l l. |
68 | Interface Attribute Value | |
69 | T{ | |
9e54434e BR |
70 | .na |
71 | .nh | |
cdb9dd9e ZL |
72 | .BR pthread_attr_init (), |
73 | .BR pthread_attr_destroy () | |
74 | T} Thread safety MT-Safe | |
75 | .TE | |
3113c7f3 | 76 | .SH STANDARDS |
4131356c AC |
77 | POSIX.1-2008. |
78 | .SH HISTORY | |
79 | POSIX.1-2001. | |
7896a155 MK |
80 | .SH NOTES |
81 | The | |
82 | .I pthread_attr_t | |
83 | type should be treated as opaque: | |
84 | any access to the object other than via pthreads functions | |
d603cc27 | 85 | is nonportable and produces undefined results. |
a14af333 | 86 | .SH EXAMPLES |
7896a155 MK |
87 | The program below optionally makes use of |
88 | .BR pthread_attr_init () | |
89 | and various related functions to initialize a thread attributes | |
90 | object that is used to create a single thread. | |
91 | Once created, the thread uses the | |
0b80cf56 | 92 | .BR pthread_getattr_np (3) |
c8f2dd47 | 93 | function (a nonstandard GNU extension) to retrieve the thread's |
7896a155 | 94 | attributes, and then displays those attributes. |
c6d039a3 | 95 | .P |
7896a155 MK |
96 | If the program is run with no command-line argument, |
97 | then it passes NULL as the | |
98 | .I attr | |
99 | argument of | |
100 | .BR pthread_create (3), | |
101 | so that the thread is created with default attributes. | |
102 | Running the program on Linux/x86-32 with the NPTL threading implementation, | |
103 | we see the following: | |
c6d039a3 | 104 | .P |
7896a155 | 105 | .in +4n |
b8302363 | 106 | .EX |
7896a155 | 107 | .\" Results from glibc 2.8, SUSE 11.0; Oct 2008 |
ee8655b5 | 108 | .RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" |
7896a155 | 109 | unlimited |
b43a3b30 | 110 | .RB "$" " ./a.out" |
7896a155 MK |
111 | Thread attributes: |
112 | Detach state = PTHREAD_CREATE_JOINABLE | |
113 | Scope = PTHREAD_SCOPE_SYSTEM | |
114 | Inherit scheduler = PTHREAD_INHERIT_SCHED | |
115 | Scheduling policy = SCHED_OTHER | |
116 | Scheduling priority = 0 | |
117 | Guard size = 4096 bytes | |
118 | Stack address = 0x40196000 | |
119 | Stack size = 0x201000 bytes | |
b8302363 | 120 | .EE |
7896a155 | 121 | .in |
c6d039a3 | 122 | .P |
7896a155 MK |
123 | When we supply a stack size as a command-line argument, |
124 | the program initializes a thread attributes object, | |
125 | sets various attributes in that object, | |
126 | and passes a pointer to the object in the call to | |
127 | .BR pthread_create (3). | |
128 | Running the program on Linux/x86-32 with the NPTL threading implementation, | |
129 | we see the following: | |
c6d039a3 | 130 | .P |
7896a155 | 131 | .in +4n |
b8302363 | 132 | .EX |
7896a155 | 133 | .\" Results from glibc 2.8, SUSE 11.0; Oct 2008 |
b43a3b30 | 134 | .RB "$" " ./a.out 0x3000000" |
7896a155 MK |
135 | posix_memalign() allocated at 0x40197000 |
136 | Thread attributes: | |
137 | Detach state = PTHREAD_CREATE_DETACHED | |
138 | Scope = PTHREAD_SCOPE_SYSTEM | |
139 | Inherit scheduler = PTHREAD_EXPLICIT_SCHED | |
140 | Scheduling policy = SCHED_OTHER | |
141 | Scheduling priority = 0 | |
142 | Guard size = 0 bytes | |
143 | Stack address = 0x40197000 | |
144 | Stack size = 0x3000000 bytes | |
b8302363 | 145 | .EE |
7896a155 | 146 | .in |
9c330504 | 147 | .SS Program source |
d84d0300 | 148 | \& |
b0b6ab4e | 149 | .\" SRC BEGIN (pthread_attr_init.c) |
e7d0bb47 | 150 | .EX |
7896a155 | 151 | #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ |
5a5208c1 | 152 | #include <err.h> |
ad3868f0 | 153 | #include <errno.h> |
7896a155 MK |
154 | #include <pthread.h> |
155 | #include <stdio.h> | |
156 | #include <stdlib.h> | |
157 | #include <unistd.h> | |
fe5dba13 | 158 | \& |
7896a155 MK |
159 | static void |
160 | display_pthread_attr(pthread_attr_t *attr, char *prefix) | |
161 | { | |
162 | int s, i; | |
163 | size_t v; | |
164 | void *stkaddr; | |
165 | struct sched_param sp; | |
fe5dba13 | 166 | \& |
7896a155 MK |
167 | s = pthread_attr_getdetachstate(attr, &i); |
168 | if (s != 0) | |
5a5208c1 | 169 | errc(EXIT_FAILURE, s, "pthread_attr_getdetachstate"); |
d1a71985 | 170 | printf("%sDetach state = %s\en", prefix, |
d917c31d AC |
171 | (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : |
172 | (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : | |
173 | "???"); | |
fe5dba13 | 174 | \& |
7896a155 MK |
175 | s = pthread_attr_getscope(attr, &i); |
176 | if (s != 0) | |
5a5208c1 | 177 | errc(EXIT_FAILURE, s, "pthread_attr_getscope"); |
d1a71985 | 178 | printf("%sScope = %s\en", prefix, |
d917c31d AC |
179 | (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : |
180 | (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : | |
181 | "???"); | |
fe5dba13 | 182 | \& |
7896a155 MK |
183 | s = pthread_attr_getinheritsched(attr, &i); |
184 | if (s != 0) | |
5a5208c1 | 185 | errc(EXIT_FAILURE, s, "pthread_attr_getinheritsched"); |
d1a71985 | 186 | printf("%sInherit scheduler = %s\en", prefix, |
d917c31d AC |
187 | (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : |
188 | (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : | |
189 | "???"); | |
fe5dba13 | 190 | \& |
7896a155 MK |
191 | s = pthread_attr_getschedpolicy(attr, &i); |
192 | if (s != 0) | |
5a5208c1 | 193 | errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy"); |
d1a71985 | 194 | printf("%sScheduling policy = %s\en", prefix, |
d917c31d AC |
195 | (i == SCHED_OTHER) ? "SCHED_OTHER" : |
196 | (i == SCHED_FIFO) ? "SCHED_FIFO" : | |
197 | (i == SCHED_RR) ? "SCHED_RR" : | |
198 | "???"); | |
fe5dba13 | 199 | \& |
7896a155 MK |
200 | s = pthread_attr_getschedparam(attr, &sp); |
201 | if (s != 0) | |
5a5208c1 | 202 | errc(EXIT_FAILURE, s, "pthread_attr_getschedparam"); |
d1a71985 | 203 | printf("%sScheduling priority = %d\en", prefix, sp.sched_priority); |
fe5dba13 | 204 | \& |
7896a155 MK |
205 | s = pthread_attr_getguardsize(attr, &v); |
206 | if (s != 0) | |
5a5208c1 | 207 | errc(EXIT_FAILURE, s, "pthread_attr_getguardsize"); |
d1a71985 | 208 | printf("%sGuard size = %zu bytes\en", prefix, v); |
fe5dba13 | 209 | \& |
7896a155 MK |
210 | s = pthread_attr_getstack(attr, &stkaddr, &v); |
211 | if (s != 0) | |
5a5208c1 | 212 | errc(EXIT_FAILURE, s, "pthread_attr_getstack"); |
d1a71985 | 213 | printf("%sStack address = %p\en", prefix, stkaddr); |
dc97703b | 214 | printf("%sStack size = %#zx bytes\en", prefix, v); |
7896a155 | 215 | } |
fe5dba13 | 216 | \& |
7896a155 MK |
217 | static void * |
218 | thread_start(void *arg) | |
219 | { | |
220 | int s; | |
221 | pthread_attr_t gattr; | |
fe5dba13 | 222 | \& |
7896a155 MK |
223 | /* pthread_getattr_np() is a non\-standard GNU extension that |
224 | retrieves the attributes of the thread specified in its | |
46b20ca1 | 225 | first argument. */ |
fe5dba13 | 226 | \& |
7896a155 MK |
227 | s = pthread_getattr_np(pthread_self(), &gattr); |
228 | if (s != 0) | |
5a5208c1 | 229 | errc(EXIT_FAILURE, s, "pthread_getattr_np"); |
fe5dba13 | 230 | \& |
d1a71985 MK |
231 | printf("Thread attributes:\en"); |
232 | display_pthread_attr(&gattr, "\et"); | |
fe5dba13 | 233 | \& |
7896a155 MK |
234 | exit(EXIT_SUCCESS); /* Terminate all threads */ |
235 | } | |
fe5dba13 | 236 | \& |
7896a155 MK |
237 | int |
238 | main(int argc, char *argv[]) | |
239 | { | |
240 | pthread_t thr; | |
241 | pthread_attr_t attr; | |
242 | pthread_attr_t *attrp; /* NULL or &attr */ | |
243 | int s; | |
fe5dba13 | 244 | \& |
7896a155 | 245 | attrp = NULL; |
fe5dba13 | 246 | \& |
7896a155 MK |
247 | /* If a command\-line argument was supplied, use it to set the |
248 | stack\-size attribute and set a few other thread attributes, | |
46b20ca1 | 249 | and set attrp pointing to thread attributes object. */ |
fe5dba13 | 250 | \& |
7896a155 | 251 | if (argc > 1) { |
7d974613 | 252 | size_t stack_size; |
7896a155 | 253 | void *sp; |
fe5dba13 | 254 | \& |
7896a155 | 255 | attrp = &attr; |
fe5dba13 | 256 | \& |
7896a155 MK |
257 | s = pthread_attr_init(&attr); |
258 | if (s != 0) | |
5a5208c1 | 259 | errc(EXIT_FAILURE, s, "pthread_attr_init"); |
fe5dba13 | 260 | \& |
7896a155 MK |
261 | s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); |
262 | if (s != 0) | |
5a5208c1 | 263 | errc(EXIT_FAILURE, s, "pthread_attr_setdetachstate"); |
fe5dba13 | 264 | \& |
7896a155 MK |
265 | s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); |
266 | if (s != 0) | |
5a5208c1 | 267 | errc(EXIT_FAILURE, s, "pthread_attr_setinheritsched"); |
fe5dba13 | 268 | \& |
7896a155 | 269 | stack_size = strtoul(argv[1], NULL, 0); |
fe5dba13 | 270 | \& |
7896a155 MK |
271 | s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); |
272 | if (s != 0) | |
5a5208c1 | 273 | errc(EXIT_FAILURE, s, "posix_memalign"); |
fe5dba13 | 274 | \& |
d1a71985 | 275 | printf("posix_memalign() allocated at %p\en", sp); |
fe5dba13 | 276 | \& |
7896a155 MK |
277 | s = pthread_attr_setstack(&attr, sp, stack_size); |
278 | if (s != 0) | |
5a5208c1 | 279 | errc(EXIT_FAILURE, s, "pthread_attr_setstack"); |
7896a155 | 280 | } |
fe5dba13 | 281 | \& |
7896a155 MK |
282 | s = pthread_create(&thr, attrp, &thread_start, NULL); |
283 | if (s != 0) | |
5a5208c1 | 284 | errc(EXIT_FAILURE, s, "pthread_create"); |
fe5dba13 | 285 | \& |
7896a155 MK |
286 | if (attrp != NULL) { |
287 | s = pthread_attr_destroy(attrp); | |
288 | if (s != 0) | |
5a5208c1 | 289 | errc(EXIT_FAILURE, s, "pthread_attr_destroy"); |
7896a155 | 290 | } |
fe5dba13 | 291 | \& |
7896a155 MK |
292 | pause(); /* Terminates when other thread calls exit() */ |
293 | } | |
e7d0bb47 | 294 | .EE |
b0b6ab4e | 295 | .\" SRC END |
7896a155 | 296 | .SH SEE ALSO |
ca8a0bd2 MK |
297 | .ad l |
298 | .nh | |
7896a155 MK |
299 | .BR pthread_attr_setaffinity_np (3), |
300 | .BR pthread_attr_setdetachstate (3), | |
301 | .BR pthread_attr_setguardsize (3), | |
302 | .BR pthread_attr_setinheritsched (3), | |
303 | .BR pthread_attr_setschedparam (3), | |
304 | .BR pthread_attr_setschedpolicy (3), | |
305 | .BR pthread_attr_setscope (3), | |
152ce70f | 306 | .BR pthread_attr_setsigmask_np (3), |
7896a155 MK |
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), | |
2b8600d3 | 312 | .BR pthread_setattr_default_np (3), |
7896a155 | 313 | .BR pthreads (7) |