1PTHREAD_ATTR_INIT(3)       Linux Programmer's Manual      PTHREAD_ATTR_INIT(3)
2
3
4

NAME

6       pthread_attr_init, pthread_attr_destroy - initialize and destroy thread
7       attributes object
8

SYNOPSIS

10       #include <pthread.h>
11
12       int pthread_attr_init(pthread_attr_t *attr);
13       int pthread_attr_destroy(pthread_attr_t *attr);
14
15       Compile and link with -pthread.
16

DESCRIPTION

18       The pthread_attr_init() function initializes the thread attributes  ob‐
19       ject  pointed  to  by  attr  with default attribute values.  After this
20       call, individual attributes of the object can be set using various  re‐
21       lated  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
24       Calling pthread_attr_init() on a thread attributes object that has  al‐
25       ready been initialized results in undefined behavior.
26
27       When a thread attributes object is no longer required, it should be de‐
28       stroyed using the pthread_attr_destroy() function.  Destroying a thread
29       attributes object has no effect on threads that were created using that
30       object.
31
32       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

RETURN VALUE

37       On success, these functions return 0; on error, they return  a  nonzero
38       error number.
39

ERRORS

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

ATTRIBUTES

46       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
47       tributes(7).
48
49       ┌───────────────────────┬───────────────┬─────────┐
50Interface              Attribute     Value   
51       ├───────────────────────┼───────────────┼─────────┤
52pthread_attr_init(),   │ Thread safety │ MT-Safe │
53pthread_attr_destroy() │               │         │
54       └───────────────────────┴───────────────┴─────────┘

CONFORMING TO

56       POSIX.1-2001, POSIX.1-2008.
57

NOTES

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

EXAMPLES

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  re‐
68       trieve the thread's attributes, and then displays those attributes.
69
70       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
75           $ 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
88       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
94           $ ./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
106   Program source
107
108       #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
115       #define handle_error_en(en, msg) \
116               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
117
118       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
126           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
134           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
142           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
150           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
159           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
164           s = pthread_attr_getguardsize(attr, &v);
165           if (s != 0)
166               handle_error_en(s, "pthread_attr_getguardsize");
167           printf("%sGuard size          = %zu bytes\n", prefix, v);
168
169           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          = %#zx bytes\n", prefix, v);
174       }
175
176       static void *
177       thread_start(void *arg)
178       {
179           int s;
180           pthread_attr_t gattr;
181
182           /* pthread_getattr_np() is a non-standard GNU extension that
183              retrieves the attributes of the thread specified in its
184              first argument */
185
186           s = pthread_getattr_np(pthread_self(), &gattr);
187           if (s != 0)
188               handle_error_en(s, "pthread_getattr_np");
189
190           printf("Thread attributes:\n");
191           display_pthread_attr(&gattr, "\t");
192
193           exit(EXIT_SUCCESS);         /* Terminate all threads */
194       }
195
196       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
204           attrp = NULL;
205
206           /* 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
210           if (argc > 1) {
211               size_t stack_size;
212               void *sp;
213
214               attrp = &attr;
215
216               s = pthread_attr_init(&attr);
217               if (s != 0)
218                   handle_error_en(s, "pthread_attr_init");
219
220               s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
221               if (s != 0)
222                   handle_error_en(s, "pthread_attr_setdetachstate");
223
224               s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
225               if (s != 0)
226                   handle_error_en(s, "pthread_attr_setinheritsched");
227
228               stack_size = strtoul(argv[1], NULL, 0);
229
230               s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
231               if (s != 0)
232                   handle_error_en(s, "posix_memalign");
233
234               printf("posix_memalign() allocated at %p\n", sp);
235
236               s = pthread_attr_setstack(&attr, sp, stack_size);
237               if (s != 0)
238                   handle_error_en(s, "pthread_attr_setstack");
239           }
240
241           s = pthread_create(&thr, attrp, &thread_start, NULL);
242           if (s != 0)
243               handle_error_en(s, "pthread_create");
244
245           if (attrp != NULL) {
246               s = pthread_attr_destroy(attrp);
247               if (s != 0)
248                   handle_error_en(s, "pthread_attr_destroy");
249           }
250
251           pause();    /* Terminates when other thread calls exit() */
252       }
253

SEE ALSO

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_setsigmask_np(3),
259       pthread_attr_setstack(3), pthread_attr_setstackaddr(3),
260       pthread_attr_setstacksize(3), pthread_create(3), pthread_getattr_np(3),
261       pthread_setattr_default_np(3), pthreads(7)
262

COLOPHON

264       This page is part of release 5.10 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/.
268
269
270
271Linux                             2020-11-01              PTHREAD_ATTR_INIT(3)
Impressum