1pthread_attr_init(3) Library Functions Manual pthread_attr_init(3)
2
6 pthread_attr_init, pthread_attr_destroy - initialize and destroy thread
7 attributes object
8
10 POSIX threads library (libpthread, -lpthread)
11
13 #include <pthread.h>
14 int pthread_attr_init(pthread_attr_t *attr);
16 int pthread_attr_destroy(pthread_attr_t *attr);
17
19 The pthread_attr_init() function initializes the thread attributes ob‐
20 ject pointed to by attr with default attribute values. After this
21 call, individual attributes of the object can be set using various re‐
22 lated functions (listed under SEE ALSO), and then the object can be
23 used in one or more pthread_create(3) calls that create threads.
24 Calling pthread_attr_init() on a thread attributes object that has al‐
26 ready been initialized results in undefined behavior.
27 When a thread attributes object is no longer required, it should be de‐
29 stroyed using the pthread_attr_destroy() function. Destroying a thread
30 attributes object has no effect on threads that were created using that
31 object.
32 Once a thread attributes object has been destroyed, it can be reini‐
34 tialized using pthread_attr_init(). Any other use of a destroyed
35 thread attributes object has undefined results.
36
38 On success, these functions return 0; on error, they return a nonzero
39 error number.
40
42 POSIX.1 documents an ENOMEM error for pthread_attr_init(); on Linux
43 these functions always succeed (but portable and future-proof applica‐
44 tions should nevertheless handle a possible error return).
45
47 For an explanation of the terms used in this section, see at‐
48 tributes(7).
49 ┌────────────────────────────────────────────┬───────────────┬─────────┐
51 │Interface │ Attribute │ Value │
52 ├────────────────────────────────────────────┼───────────────┼─────────┤
53 │pthread_attr_init(), pthread_attr_destroy() │ Thread safety │ MT-Safe │
54 └────────────────────────────────────────────┴───────────────┴─────────┘
55
57 POSIX.1-2008.
58
60 POSIX.1-2001.
61
63 The pthread_attr_t type should be treated as opaque: any access to the
64 object other than via pthreads functions is nonportable and produces
65 undefined results.
66
68 The program below optionally makes use of pthread_attr_init() and vari‐
69 ous related functions to initialize a thread attributes object that is
70 used to create a single thread. Once created, the thread uses the
71 pthread_getattr_np(3) function (a nonstandard GNU extension) to re‐
72 trieve the thread's attributes, and then displays those attributes.
73 If the program is run with no command-line argument, then it passes
75 NULL as the attr argument of pthread_create(3), so that the thread is
76 created with default attributes. Running the program on Linux/x86-32
77 with the NPTL threading implementation, we see the following:
78 $ ulimit -s # No stack limit ==> default stack size is 2 MB
80 unlimited
81 $ ./a.out
82 Thread attributes:
83 Detach state = PTHREAD_CREATE_JOINABLE
84 Scope = PTHREAD_SCOPE_SYSTEM
85 Inherit scheduler = PTHREAD_INHERIT_SCHED
86 Scheduling policy = SCHED_OTHER
87 Scheduling priority = 0
88 Guard size = 4096 bytes
89 Stack address = 0x40196000
90 Stack size = 0x201000 bytes
91 When we supply a stack size as a command-line argument, the program
93 initializes a thread attributes object, sets various attributes in that
94 object, and passes a pointer to the object in the call to pthread_cre‐
95 ate(3). Running the program on Linux/x86-32 with the NPTL threading
96 implementation, we see the following:
97 $ ./a.out 0x3000000
99 posix_memalign() allocated at 0x40197000
100 Thread attributes:
101 Detach state = PTHREAD_CREATE_DETACHED
102 Scope = PTHREAD_SCOPE_SYSTEM
103 Inherit scheduler = PTHREAD_EXPLICIT_SCHED
104 Scheduling policy = SCHED_OTHER
105 Scheduling priority = 0
106 Guard size = 0 bytes
107 Stack address = 0x40197000
108 Stack size = 0x3000000 bytes
109 Program source
111 #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */
113 #include <err.h>
114 #include <errno.h>
115 #include <pthread.h>
116 #include <stdio.h>
117 #include <stdlib.h>
118 #include <unistd.h>
119 static void
121 display_pthread_attr(pthread_attr_t *attr, char *prefix)
122 {
123 int s, i;
124 size_t v;
125 void *stkaddr;
126 struct sched_param sp;
127 s = pthread_attr_getdetachstate(attr, &i);
129 if (s != 0)
130 errc(EXIT_FAILURE, s, "pthread_attr_getdetachstate");
131 printf("%sDetach state = %s\n", prefix,
132 (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
133 (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
134 "???");
135 s = pthread_attr_getscope(attr, &i);
137 if (s != 0)
138 errc(EXIT_FAILURE, s, "pthread_attr_getscope");
139 printf("%sScope = %s\n", prefix,
140 (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" :
141 (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
142 "???");
143 s = pthread_attr_getinheritsched(attr, &i);
145 if (s != 0)
146 errc(EXIT_FAILURE, s, "pthread_attr_getinheritsched");
147 printf("%sInherit scheduler = %s\n", prefix,
148 (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" :
149 (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
150 "???");
151 s = pthread_attr_getschedpolicy(attr, &i);
153 if (s != 0)
154 errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy");
155 printf("%sScheduling policy = %s\n", prefix,
156 (i == SCHED_OTHER) ? "SCHED_OTHER" :
157 (i == SCHED_FIFO) ? "SCHED_FIFO" :
158 (i == SCHED_RR) ? "SCHED_RR" :
159 "???");
160 s = pthread_attr_getschedparam(attr, &sp);
162 if (s != 0)
163 errc(EXIT_FAILURE, s, "pthread_attr_getschedparam");
164 printf("%sScheduling priority = %d\n", prefix, sp.sched_priority);
165 s = pthread_attr_getguardsize(attr, &v);
167 if (s != 0)
168 errc(EXIT_FAILURE, s, "pthread_attr_getguardsize");
169 printf("%sGuard size = %zu bytes\n", prefix, v);
170 s = pthread_attr_getstack(attr, &stkaddr, &v);
172 if (s != 0)
173 errc(EXIT_FAILURE, s, "pthread_attr_getstack");
174 printf("%sStack address = %p\n", prefix, stkaddr);
175 printf("%sStack size = %#zx bytes\n", prefix, v);
176 }
177 static void *
179 thread_start(void *arg)
180 {
181 int s;
182 pthread_attr_t gattr;
183 /* pthread_getattr_np() is a non-standard GNU extension that
185 retrieves the attributes of the thread specified in its
186 first argument. */
187 s = pthread_getattr_np(pthread_self(), &gattr);
189 if (s != 0)
190 errc(EXIT_FAILURE, s, "pthread_getattr_np");
191 printf("Thread attributes:\n");
193 display_pthread_attr(&gattr, "\t");
194 exit(EXIT_SUCCESS); /* Terminate all threads */
196 }
197 int
199 main(int argc, char *argv[])
200 {
201 pthread_t thr;
202 pthread_attr_t attr;
203 pthread_attr_t *attrp; /* NULL or &attr */
204 int s;
205 attrp = NULL;
207 /* If a command-line argument was supplied, use it to set the
209 stack-size attribute and set a few other thread attributes,
210 and set attrp pointing to thread attributes object. */
211 if (argc > 1) {
213 size_t stack_size;
214 void *sp;
215 attrp = &attr;
217 s = pthread_attr_init(&attr);
219 if (s != 0)
220 errc(EXIT_FAILURE, s, "pthread_attr_init");
221 s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
223 if (s != 0)
224 errc(EXIT_FAILURE, s, "pthread_attr_setdetachstate");
225 s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
227 if (s != 0)
228 errc(EXIT_FAILURE, s, "pthread_attr_setinheritsched");
229 stack_size = strtoul(argv[1], NULL, 0);
231 s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
233 if (s != 0)
234 errc(EXIT_FAILURE, s, "posix_memalign");
235 printf("posix_memalign() allocated at %p\n", sp);
237 s = pthread_attr_setstack(&attr, sp, stack_size);
239 if (s != 0)
240 errc(EXIT_FAILURE, s, "pthread_attr_setstack");
241 }
242 s = pthread_create(&thr, attrp, &thread_start, NULL);
244 if (s != 0)
245 errc(EXIT_FAILURE, s, "pthread_create");
246 if (attrp != NULL) {
248 s = pthread_attr_destroy(attrp);
249 if (s != 0)
250 errc(EXIT_FAILURE, s, "pthread_attr_destroy");
251 }
252 pause(); /* Terminates when other thread calls exit() */
254 }
255
257 pthread_attr_setaffinity_np(3), pthread_attr_setdetachstate(3),
258 pthread_attr_setguardsize(3), pthread_attr_setinheritsched(3),
259 pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3),
260 pthread_attr_setscope(3), pthread_attr_setsigmask_np(3),
261 pthread_attr_setstack(3), pthread_attr_setstackaddr(3),
262 pthread_attr_setstacksize(3), pthread_create(3), pthread_getattr_np(3),
263 pthread_setattr_default_np(3), pthreads(7)
264Linux man-pages 6.04 2023-03-30 pthread_attr_init(3)