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
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
24       Calling pthread_attr_init() on a  thread  attributes  object  that  has
25       already been initialized results in undefined behavior.
26
27       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
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  non-zero
38       error number.
39

ERRORS

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

CONFORMING TO

46       POSIX.1-2001.
47

NOTES

49       The  pthread_attr_t type should be treated as opaque: any access to the
50       object other than via pthreads functions is non-portable  and  produces
51       undefined results.
52

EXAMPLE

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()  function  (a  non-standard  GNU   extension)   to
58       retrieve the thread's attributes, and then displays those attributes.
59
60       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
65           $ 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
78       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
84           $ ./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
96   Program source
97
98       #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
105       #define handle_error_en(en, msg) \
106               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
107
108       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
116           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
124           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
132           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
140           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
149           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
154           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
159           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
166       static void *
167       thread_start(void *arg)
168       {
169           int s;
170           pthread_attr_t gattr;
171
172           /* pthread_getattr_np() is a non-standard GNU extension that
173              retrieves the attributes of the thread specified in its
174              first argument */
175
176           s = pthread_getattr_np(pthread_self(), &gattr);
177           if (s != 0)
178               handle_error_en(s, "pthread_getattr_np");
179
180           printf("Thread attributes:\n");
181           display_pthread_attr(&gattr, "\t");
182
183           exit(EXIT_SUCCESS);         /* Terminate all threads */
184       }
185
186       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
194           attrp = NULL;
195
196           /* 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
200           if (argc > 1) {
201               int stack_size;
202               void *sp;
203
204               attrp = &attr;
205
206               s = pthread_attr_init(&attr);
207               if (s != 0)
208                   handle_error_en(s, "pthread_attr_init");
209
210               s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
211               if (s != 0)
212                   handle_error_en(s, "pthread_attr_setdetachstate");
213
214               s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
215               if (s != 0)
216                   handle_error_en(s, "pthread_attr_setinheritsched");
217
218               stack_size = strtoul(argv[1], NULL, 0);
219
220               s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
221               if (s != 0)
222                   handle_error_en(s, "posix_memalign");
223
224               printf("posix_memalign() allocated at %p\n", sp);
225
226               s = pthread_attr_setstack(&attr, sp, stack_size);
227               if (s != 0)
228                   handle_error_en(s, "pthread_attr_setstack");
229           }
230
231           s = pthread_create(&thr, attrp, &thread_start, NULL);
232           if (s != 0)
233               handle_error_en(s, "pthread_create");
234
235           if (attrp != NULL) {
236               s = pthread_attr_destroy(attrp);
237               if (s != 0)
238                   handle_error_en(s, "pthread_attr_destroy");
239           }
240
241           pause();    /* Terminates when other thread calls exit() */
242       }
243

SEE ALSO

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),  pthread_attr_set‐
249       stackaddr(3),     pthread_attr_setstacksize(3),      pthread_create(3),
250       pthread_getattr_np(3), pthreads(7)
251

COLOPHON

253       This  page  is  part of release 3.22 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/.
256
257
258
259Linux                             2008-11-11              PTHREAD_ATTR_INIT(3)
Impressum