]>
Commit | Line | Data |
---|---|---|
7896a155 MK |
1 | .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
7896a155 MK |
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. | |
8 | .\" | |
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. | |
13 | .\" | |
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 | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
7896a155 | 25 | .\" |
9ba01802 | 26 | .TH PTHREAD_ATTR_INIT 3 2019-03-06 "Linux" "Linux Programmer's Manual" |
7896a155 MK |
27 | .SH NAME |
28 | pthread_attr_init, pthread_attr_destroy \- initialize and destroy | |
29 | thread attributes object | |
30 | .SH SYNOPSIS | |
31 | .nf | |
32 | .B #include <pthread.h> | |
f90f031e | 33 | .PP |
7896a155 MK |
34 | .BI "int pthread_attr_init(pthread_attr_t *" attr ); |
35 | .BI "int pthread_attr_destroy(pthread_attr_t *" attr ); | |
68e4db0a | 36 | .PP |
7896a155 | 37 | Compile and link with \fI\-pthread\fP. |
6030f2d8 | 38 | .fi |
7896a155 MK |
39 | .SH DESCRIPTION |
40 | The | |
41 | .BR pthread_attr_init () | |
42 | function initializes the thread attributes object pointed to by | |
43 | .IR attr | |
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. | |
847e0d88 | 50 | .PP |
c5571b61 | 51 | Calling |
7896a155 MK |
52 | .BR pthread_attr_init () |
53 | on a thread attributes object that has already been initialized | |
54 | results in undefined behavior. | |
847e0d88 | 55 | .PP |
7896a155 MK |
56 | When a thread attributes object is no longer required, |
57 | it should be destroyed using the | |
58 | .BR pthread_attr_destroy () | |
59 | function. | |
60 | Destroying a thread attributes object has no effect | |
61 | on threads that were created using that object. | |
847e0d88 | 62 | .PP |
7896a155 MK |
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. | |
68 | .SH RETURN VALUE | |
69 | On success, these functions return 0; | |
c7094399 | 70 | on error, they return a nonzero error number. |
7896a155 | 71 | .SH ERRORS |
8bf49a72 | 72 | POSIX.1 documents an |
7896a155 MK |
73 | .B ENOMEM |
74 | error for | |
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). | |
cdb9dd9e ZL |
79 | .SH ATTRIBUTES |
80 | For an explanation of the terms used in this section, see | |
81 | .BR attributes (7). | |
74714ea8 | 82 | .ad l |
cdb9dd9e ZL |
83 | .TS |
84 | allbox; | |
85 | lbw22 lb lb | |
86 | l l l. | |
87 | Interface Attribute Value | |
88 | T{ | |
89 | .BR pthread_attr_init (), | |
90 | .BR pthread_attr_destroy () | |
91 | T} Thread safety MT-Safe | |
92 | .TE | |
74714ea8 | 93 | .ad |
7896a155 | 94 | .SH CONFORMING TO |
8bf49a72 | 95 | POSIX.1-2001, POSIX.1-2008. |
7896a155 MK |
96 | .SH NOTES |
97 | The | |
98 | .I pthread_attr_t | |
99 | type should be treated as opaque: | |
100 | any access to the object other than via pthreads functions | |
d603cc27 | 101 | is nonportable and produces undefined results. |
7896a155 MK |
102 | .SH EXAMPLE |
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 | |
0b80cf56 | 108 | .BR pthread_getattr_np (3) |
c8f2dd47 | 109 | function (a nonstandard GNU extension) to retrieve the thread's |
7896a155 | 110 | attributes, and then displays those attributes. |
847e0d88 | 111 | .PP |
7896a155 MK |
112 | If the program is run with no command-line argument, |
113 | then it passes NULL as the | |
114 | .I attr | |
115 | argument of | |
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: | |
847e0d88 | 120 | .PP |
7896a155 | 121 | .in +4n |
b8302363 | 122 | .EX |
7896a155 | 123 | .\" Results from glibc 2.8, SUSE 11.0; Oct 2008 |
ee8655b5 | 124 | .RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" |
7896a155 | 125 | unlimited |
b43a3b30 | 126 | .RB "$" " ./a.out" |
7896a155 MK |
127 | Thread attributes: |
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 | |
b8302363 | 136 | .EE |
7896a155 | 137 | .in |
847e0d88 | 138 | .PP |
7896a155 MK |
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: | |
847e0d88 | 146 | .PP |
7896a155 | 147 | .in +4n |
b8302363 | 148 | .EX |
7896a155 | 149 | .\" Results from glibc 2.8, SUSE 11.0; Oct 2008 |
b43a3b30 | 150 | .RB "$" " ./a.out 0x3000000" |
7896a155 MK |
151 | posix_memalign() allocated at 0x40197000 |
152 | Thread attributes: | |
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 | |
158 | Guard size = 0 bytes | |
159 | Stack address = 0x40197000 | |
160 | Stack size = 0x3000000 bytes | |
b8302363 | 161 | .EE |
7896a155 | 162 | .in |
9c330504 | 163 | .SS Program source |
d84d0300 | 164 | \& |
e7d0bb47 | 165 | .EX |
7896a155 MK |
166 | #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ |
167 | #include <pthread.h> | |
168 | #include <stdio.h> | |
169 | #include <stdlib.h> | |
170 | #include <unistd.h> | |
171 | #include <errno.h> | |
172 | ||
d1a71985 | 173 | #define handle_error_en(en, msg) \e |
940c8ce2 | 174 | do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) |
7896a155 MK |
175 | |
176 | static void | |
177 | display_pthread_attr(pthread_attr_t *attr, char *prefix) | |
178 | { | |
179 | int s, i; | |
180 | size_t v; | |
181 | void *stkaddr; | |
182 | struct sched_param sp; | |
183 | ||
184 | s = pthread_attr_getdetachstate(attr, &i); | |
185 | if (s != 0) | |
940c8ce2 | 186 | handle_error_en(s, "pthread_attr_getdetachstate"); |
d1a71985 | 187 | printf("%sDetach state = %s\en", prefix, |
7896a155 MK |
188 | (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : |
189 | (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : | |
190 | "???"); | |
191 | ||
192 | s = pthread_attr_getscope(attr, &i); | |
193 | if (s != 0) | |
940c8ce2 | 194 | handle_error_en(s, "pthread_attr_getscope"); |
d1a71985 | 195 | printf("%sScope = %s\en", prefix, |
7896a155 MK |
196 | (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : |
197 | (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : | |
198 | "???"); | |
199 | ||
200 | s = pthread_attr_getinheritsched(attr, &i); | |
201 | if (s != 0) | |
940c8ce2 | 202 | handle_error_en(s, "pthread_attr_getinheritsched"); |
d1a71985 | 203 | printf("%sInherit scheduler = %s\en", prefix, |
7896a155 MK |
204 | (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : |
205 | (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : | |
206 | "???"); | |
207 | ||
208 | s = pthread_attr_getschedpolicy(attr, &i); | |
209 | if (s != 0) | |
940c8ce2 | 210 | handle_error_en(s, "pthread_attr_getschedpolicy"); |
d1a71985 | 211 | printf("%sScheduling policy = %s\en", prefix, |
7896a155 MK |
212 | (i == SCHED_OTHER) ? "SCHED_OTHER" : |
213 | (i == SCHED_FIFO) ? "SCHED_FIFO" : | |
214 | (i == SCHED_RR) ? "SCHED_RR" : | |
215 | "???"); | |
216 | ||
217 | s = pthread_attr_getschedparam(attr, &sp); | |
218 | if (s != 0) | |
940c8ce2 | 219 | handle_error_en(s, "pthread_attr_getschedparam"); |
d1a71985 | 220 | printf("%sScheduling priority = %d\en", prefix, sp.sched_priority); |
7896a155 MK |
221 | |
222 | s = pthread_attr_getguardsize(attr, &v); | |
223 | if (s != 0) | |
940c8ce2 | 224 | handle_error_en(s, "pthread_attr_getguardsize"); |
d1a71985 | 225 | printf("%sGuard size = %zu bytes\en", prefix, v); |
7896a155 MK |
226 | |
227 | s = pthread_attr_getstack(attr, &stkaddr, &v); | |
228 | if (s != 0) | |
940c8ce2 | 229 | handle_error_en(s, "pthread_attr_getstack"); |
d1a71985 MK |
230 | printf("%sStack address = %p\en", prefix, stkaddr); |
231 | printf("%sStack size = 0x%zx bytes\en", prefix, v); | |
7896a155 MK |
232 | } |
233 | ||
234 | static void * | |
235 | thread_start(void *arg) | |
236 | { | |
237 | int s; | |
238 | pthread_attr_t gattr; | |
239 | ||
240 | /* pthread_getattr_np() is a non\-standard GNU extension that | |
241 | retrieves the attributes of the thread specified in its | |
242 | first argument */ | |
243 | ||
244 | s = pthread_getattr_np(pthread_self(), &gattr); | |
245 | if (s != 0) | |
940c8ce2 | 246 | handle_error_en(s, "pthread_getattr_np"); |
7896a155 | 247 | |
d1a71985 MK |
248 | printf("Thread attributes:\en"); |
249 | display_pthread_attr(&gattr, "\et"); | |
7896a155 MK |
250 | |
251 | exit(EXIT_SUCCESS); /* Terminate all threads */ | |
252 | } | |
253 | ||
254 | int | |
255 | main(int argc, char *argv[]) | |
256 | { | |
257 | pthread_t thr; | |
258 | pthread_attr_t attr; | |
259 | pthread_attr_t *attrp; /* NULL or &attr */ | |
260 | int s; | |
261 | ||
262 | attrp = NULL; | |
263 | ||
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 */ | |
267 | ||
268 | if (argc > 1) { | |
269 | int stack_size; | |
270 | void *sp; | |
271 | ||
272 | attrp = &attr; | |
273 | ||
274 | s = pthread_attr_init(&attr); | |
275 | if (s != 0) | |
940c8ce2 | 276 | handle_error_en(s, "pthread_attr_init"); |
7896a155 MK |
277 | |
278 | s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); | |
279 | if (s != 0) | |
940c8ce2 | 280 | handle_error_en(s, "pthread_attr_setdetachstate"); |
7896a155 MK |
281 | |
282 | s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); | |
283 | if (s != 0) | |
940c8ce2 | 284 | handle_error_en(s, "pthread_attr_setinheritsched"); |
7896a155 MK |
285 | |
286 | stack_size = strtoul(argv[1], NULL, 0); | |
287 | ||
288 | s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); | |
289 | if (s != 0) | |
940c8ce2 | 290 | handle_error_en(s, "posix_memalign"); |
7896a155 | 291 | |
d1a71985 | 292 | printf("posix_memalign() allocated at %p\en", sp); |
7896a155 MK |
293 | |
294 | s = pthread_attr_setstack(&attr, sp, stack_size); | |
295 | if (s != 0) | |
940c8ce2 | 296 | handle_error_en(s, "pthread_attr_setstack"); |
7896a155 MK |
297 | } |
298 | ||
299 | s = pthread_create(&thr, attrp, &thread_start, NULL); | |
300 | if (s != 0) | |
940c8ce2 | 301 | handle_error_en(s, "pthread_create"); |
7896a155 MK |
302 | |
303 | if (attrp != NULL) { | |
304 | s = pthread_attr_destroy(attrp); | |
305 | if (s != 0) | |
940c8ce2 | 306 | handle_error_en(s, "pthread_attr_destroy"); |
7896a155 MK |
307 | } |
308 | ||
309 | pause(); /* Terminates when other thread calls exit() */ | |
310 | } | |
e7d0bb47 | 311 | .EE |
7896a155 | 312 | .SH SEE ALSO |
ca8a0bd2 MK |
313 | .ad l |
314 | .nh | |
7896a155 MK |
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), | |
2b8600d3 | 327 | .BR pthread_setattr_default_np (3), |
7896a155 | 328 | .BR pthreads (7) |