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-2001 documents an ENOMEM error for pthread_attr_init(); on
42 Linux these functions always succeed (but portable and future-proof
43 applications should nevertheless handle a possible error return).
44
46 POSIX.1-2001.
47
49 The pthread_attr_t type should be treated as opaque: any access to the
50 object other than via pthreads functions is nonportable and produces
51 undefined results.
52
54 The program below optionally makes use of pthread_attr_init() and vari‐
55 ous related functions to initialize a thread attributes object that is
56 used to create a single thread. Once created, the thread uses the
57 pthread_getattr_np(3) function (a nonstandard GNU extension) to
58 retrieve the thread's attributes, and then displays those attributes.
59 If the program is run with no command-line argument, then it passes
61 NULL as the attr argument of pthread_create(3), so that the thread is
62 created with default attributes. Running the program on Linux/x86-32
63 with the NPTL threading implementation, we see the following:
64 $ ulimit -s # No stack imit ==> default stack size is 2MB
66 unlimited
67 $ ./a.out
68 Thread attributes:
69 Detach state = PTHREAD_CREATE_JOINABLE
70 Scope = PTHREAD_SCOPE_SYSTEM
71 Inherit scheduler = PTHREAD_INHERIT_SCHED
72 Scheduling policy = SCHED_OTHER
73 Scheduling priority = 0
74 Guard size = 4096 bytes
75 Stack address = 0x40196000
76 Stack size = 0x201000 bytes
77 When we supply a stack size as a command-line argument, the program
79 initializes a thread attributes object, sets various attributes in that
80 object, and passes a pointer to the object in the call to pthread_cre‐
81 ate(3). Running the program on Linux/x86-32 with the NPTL threading
82 implementation, we see the following:
83 $ ./a.out 0x3000000
85 posix_memalign() allocated at 0x40197000
86 Thread attributes:
87 Detach state = PTHREAD_CREATE_DETACHED
88 Scope = PTHREAD_SCOPE_SYSTEM
89 Inherit scheduler = PTHREAD_EXPLICIT_SCHED
90 Scheduling policy = SCHED_OTHER
91 Scheduling priority = 0
92 Guard size = 0 bytes
93 Stack address = 0x40197000
94 Stack size = 0x3000000 bytes
95 Program source
97 #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */
99 #include <pthread.h>
100 #include <stdio.h>
101 #include <stdlib.h>
102 #include <unistd.h>
103 #include <errno.h>
104 #define handle_error_en(en, msg) \
106 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
107 static void
109 display_pthread_attr(pthread_attr_t *attr, char *prefix)
110 {
111 int s, i;
112 size_t v;
113 void *stkaddr;
114 struct sched_param sp;
115 s = pthread_attr_getdetachstate(attr, &i);
117 if (s != 0)
118 handle_error_en(s, "pthread_attr_getdetachstate");
119 printf("%sDetach state = %s\n", prefix,
120 (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
121 (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
122 "???");
123 s = pthread_attr_getscope(attr, &i);
125 if (s != 0)
126 handle_error_en(s, "pthread_attr_getscope");
127 printf("%sScope = %s\n", prefix,
128 (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" :
129 (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
130 "???");
131 s = pthread_attr_getinheritsched(attr, &i);
133 if (s != 0)
134 handle_error_en(s, "pthread_attr_getinheritsched");
135 printf("%sInherit scheduler = %s\n", prefix,
136 (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" :
137 (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
138 "???");
139 s = pthread_attr_getschedpolicy(attr, &i);
141 if (s != 0)
142 handle_error_en(s, "pthread_attr_getschedpolicy");
143 printf("%sScheduling policy = %s\n", prefix,
144 (i == SCHED_OTHER) ? "SCHED_OTHER" :
145 (i == SCHED_FIFO) ? "SCHED_FIFO" :
146 (i == SCHED_RR) ? "SCHED_RR" :
147 "???");
148 s = pthread_attr_getschedparam(attr, &sp);
150 if (s != 0)
151 handle_error_en(s, "pthread_attr_getschedparam");
152 printf("%sScheduling priority = %d\n", prefix, sp.sched_priority);
153 s = pthread_attr_getguardsize(attr, &v);
155 if (s != 0)
156 handle_error_en(s, "pthread_attr_getguardsize");
157 printf("%sGuard size = %d bytes\n", prefix, v);
158 s = pthread_attr_getstack(attr, &stkaddr, &v);
160 if (s != 0)
161 handle_error_en(s, "pthread_attr_getstack");
162 printf("%sStack address = %p\n", prefix, stkaddr);
163 printf("%sStack size = 0x%x bytes\n", prefix, v);
164 }
165 static void *
167 thread_start(void *arg)
168 {
169 int s;
170 pthread_attr_t gattr;
171 /* pthread_getattr_np() is a non-standard GNU extension that
173 retrieves the attributes of the thread specified in its
174 first argument */
175 s = pthread_getattr_np(pthread_self(), &gattr);
177 if (s != 0)
178 handle_error_en(s, "pthread_getattr_np");
179 printf("Thread attributes:\n");
181 display_pthread_attr(&gattr, "\t");
182 exit(EXIT_SUCCESS); /* Terminate all threads */
184 }
185 int
187 main(int argc, char *argv[])
188 {
189 pthread_t thr;
190 pthread_attr_t attr;
191 pthread_attr_t *attrp; /* NULL or &attr */
192 int s;
193 attrp = NULL;
195 /* If a command-line argument was supplied, use it to set the
197 stack-size attribute and set a few other thread attributes,
198 and set attrp pointing to thread attributes object */
199 if (argc > 1) {
201 int stack_size;
202 void *sp;
203 attrp = &attr;
205 s = pthread_attr_init(&attr);
207 if (s != 0)
208 handle_error_en(s, "pthread_attr_init");
209 s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
211 if (s != 0)
212 handle_error_en(s, "pthread_attr_setdetachstate");
213 s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
215 if (s != 0)
216 handle_error_en(s, "pthread_attr_setinheritsched");
217 stack_size = strtoul(argv[1], NULL, 0);
219 s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
221 if (s != 0)
222 handle_error_en(s, "posix_memalign");
223 printf("posix_memalign() allocated at %p\n", sp);
225 s = pthread_attr_setstack(&attr, sp, stack_size);
227 if (s != 0)
228 handle_error_en(s, "pthread_attr_setstack");
229 }
230 s = pthread_create(&thr, attrp, &thread_start, NULL);
232 if (s != 0)
233 handle_error_en(s, "pthread_create");
234 if (attrp != NULL) {
236 s = pthread_attr_destroy(attrp);
237 if (s != 0)
238 handle_error_en(s, "pthread_attr_destroy");
239 }
240 pause(); /* Terminates when other thread calls exit() */
242 }
243
245 pthread_attr_setaffinity_np(3), pthread_attr_setdetachstate(3),
246 pthread_attr_setguardsize(3), pthread_attr_setinheritsched(3),
247 pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3),
248 pthread_attr_setscope(3), pthread_attr_setstack(3),
249 pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3),
250 pthread_create(3), pthread_getattr_np(3), pthreads(7)
251
253 This page is part of release 3.53 of the Linux man-pages project. A
254 description of the project, and information about reporting bugs, can
255 be found at http://www.kernel.org/doc/man-pages/.
256Linux 2008-11-11 PTHREAD_ATTR_INIT(3)