man3/pthread_attr_init.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(verbatim)
   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.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH PTHREAD_ATTR_INIT 3 2008-11-11 "Linux" "Linux Programmer's Manual"
  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>
  33
  34 .BI "int pthread_attr_init(pthread_attr_t *" attr );
  35 .BI "int pthread_attr_destroy(pthread_attr_t *" attr );
  36 .sp
  37 Compile and link with \fI\-pthread\fP.
  38 .fi
  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.
  50
  51 Calling
  52 .BR pthread_attr_init ()
  53 on a thread attributes object that has already been initialized
  54 results in undefined behavior.
  55
  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.
  62
  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;
  70 on error, they return a nonzero error number.
  71 .SH ERRORS
  72 POSIX.1-2001 documents an
  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).
  79 .SH CONFORMING TO
  80 POSIX.1-2001.
  81 .SH NOTES
  82 The
  83 .I pthread_attr_t
  84 type should be treated as opaque:
  85 any access to the object other than via pthreads functions
  86 is nonportable and produces undefined results.
  87 .SH EXAMPLE
  88 The program below optionally makes use of
  89 .BR pthread_attr_init ()
  90 and various related functions to initialize a thread attributes
  91 object that is used to create a single thread.
  92 Once created, the thread uses the
  93 .BR pthread_getattr_np (3)
  94 function (a nonstandard GNU extension) to retrieve the thread's
  95 attributes, and then displays those attributes.
  96
  97 If the program is run with no command-line argument,
  98 then it passes NULL as the
  99 .I attr
 100 argument of
 101 .BR pthread_create (3),
 102 so that the thread is created with default attributes.
 103 Running the program on Linux/x86-32 with the NPTL threading implementation,
 104 we see the following:
 105
 106 .in +4n
 107 .nf
 108 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
 109 .RB "$" " ulimit \-s" "       # No stack imit ==> default stack size is 2MB"
 110 unlimited
 111 .RB "$" " ./a.out"
 112 Thread attributes:
 113         Detach state        = PTHREAD_CREATE_JOINABLE
 114         Scope               = PTHREAD_SCOPE_SYSTEM
 115         Inherit scheduler   = PTHREAD_INHERIT_SCHED
 116         Scheduling policy   = SCHED_OTHER
 117         Scheduling priority = 0
 118         Guard size          = 4096 bytes
 119         Stack address       = 0x40196000
 120         Stack size          = 0x201000 bytes
 121 .fi
 122 .in
 123
 124 When we supply a stack size as a command-line argument,
 125 the program initializes a thread attributes object,
 126 sets various attributes in that object,
 127 and passes a pointer to the object in the call to
 128 .BR pthread_create (3).
 129 Running the program on Linux/x86-32 with the NPTL threading implementation,
 130 we see the following:
 131
 132 .in +4n
 133 .nf
 134 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
 135 .RB "$" " ./a.out 0x3000000"
 136 posix_memalign() allocated at 0x40197000
 137 Thread attributes:
 138         Detach state        = PTHREAD_CREATE_DETACHED
 139         Scope               = PTHREAD_SCOPE_SYSTEM
 140         Inherit scheduler   = PTHREAD_EXPLICIT_SCHED
 141         Scheduling policy   = SCHED_OTHER
 142         Scheduling priority = 0
 143         Guard size          = 0 bytes
 144         Stack address       = 0x40197000
 145         Stack size          = 0x3000000 bytes
 146 .fi
 147 .in
 148 .SS Program source
 149 \&
 150 .nf
 151 #define _GNU_SOURCE     /* To get pthread_getattr_np() declaration */
 152 #include <pthread.h>
 153 #include <stdio.h>
 154 #include <stdlib.h>
 155 #include <unistd.h>
 156 #include <errno.h>
 157
 158 #define handle_error_en(en, msg) \\
 159         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 160
 161 static void
 162 display_pthread_attr(pthread_attr_t *attr, char *prefix)
 163 {
 164     int s, i;
 165     size_t v;
 166     void *stkaddr;
 167     struct sched_param sp;
 168
 169     s = pthread_attr_getdetachstate(attr, &i);
 170     if (s != 0)
 171         handle_error_en(s, "pthread_attr_getdetachstate");
 172     printf("%sDetach state        = %s\\n", prefix,
 173             (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
 174             (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
 175             "???");
 176
 177     s = pthread_attr_getscope(attr, &i);
 178     if (s != 0)
 179         handle_error_en(s, "pthread_attr_getscope");
 180     printf("%sScope               = %s\\n", prefix,
 181             (i == PTHREAD_SCOPE_SYSTEM)  ? "PTHREAD_SCOPE_SYSTEM" :
 182             (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
 183             "???");
 184
 185     s = pthread_attr_getinheritsched(attr, &i);
 186     if (s != 0)
 187         handle_error_en(s, "pthread_attr_getinheritsched");
 188     printf("%sInherit scheduler   = %s\\n", prefix,
 189             (i == PTHREAD_INHERIT_SCHED)  ? "PTHREAD_INHERIT_SCHED" :
 190             (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
 191             "???");
 192
 193     s = pthread_attr_getschedpolicy(attr, &i);
 194     if (s != 0)
 195         handle_error_en(s, "pthread_attr_getschedpolicy");
 196     printf("%sScheduling policy   = %s\\n", prefix,
 197             (i == SCHED_OTHER) ? "SCHED_OTHER" :
 198             (i == SCHED_FIFO)  ? "SCHED_FIFO" :
 199             (i == SCHED_RR)    ? "SCHED_RR" :
 200             "???");
 201
 202     s = pthread_attr_getschedparam(attr, &sp);
 203     if (s != 0)
 204         handle_error_en(s, "pthread_attr_getschedparam");
 205     printf("%sScheduling priority = %d\\n", prefix, sp.sched_priority);
 206
 207     s = pthread_attr_getguardsize(attr, &v);
 208     if (s != 0)
 209         handle_error_en(s, "pthread_attr_getguardsize");
 210     printf("%sGuard size          = %d bytes\\n", prefix, v);
 211
 212     s = pthread_attr_getstack(attr, &stkaddr, &v);
 213     if (s != 0)
 214         handle_error_en(s, "pthread_attr_getstack");
 215     printf("%sStack address       = %p\\n", prefix, stkaddr);
 216     printf("%sStack size          = 0x%x bytes\\n", prefix, v);
 217 }
 218
 219 static void *
 220 thread_start(void *arg)
 221 {
 222     int s;
 223     pthread_attr_t gattr;
 224
 225     /* pthread_getattr_np() is a non\-standard GNU extension that
 226        retrieves the attributes of the thread specified in its
 227        first argument */
 228
 229     s = pthread_getattr_np(pthread_self(), &gattr);
 230     if (s != 0)
 231         handle_error_en(s, "pthread_getattr_np");
 232
 233     printf("Thread attributes:\\n");
 234     display_pthread_attr(&gattr, "\\t");
 235
 236     exit(EXIT_SUCCESS);         /* Terminate all threads */
 237 }
 238
 239 int
 240 main(int argc, char *argv[])
 241 {
 242     pthread_t thr;
 243     pthread_attr_t attr;
 244     pthread_attr_t *attrp;      /* NULL or &attr */
 245     int s;
 246
 247     attrp = NULL;
 248
 249     /* If a command\-line argument was supplied, use it to set the
 250        stack\-size attribute and set a few other thread attributes,
 251        and set attrp pointing to thread attributes object */
 252
 253     if (argc > 1) {
 254         int stack_size;
 255         void *sp;
 256
 257         attrp = &attr;
 258
 259         s = pthread_attr_init(&attr);
 260         if (s != 0)
 261             handle_error_en(s, "pthread_attr_init");
 262
 263         s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
 264         if (s != 0)
 265             handle_error_en(s, "pthread_attr_setdetachstate");
 266
 267         s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
 268         if (s != 0)
 269             handle_error_en(s, "pthread_attr_setinheritsched");
 270
 271         stack_size = strtoul(argv[1], NULL, 0);
 272
 273         s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
 274         if (s != 0)
 275             handle_error_en(s, "posix_memalign");
 276
 277         printf("posix_memalign() allocated at %p\\n", sp);
 278
 279         s = pthread_attr_setstack(&attr, sp, stack_size);
 280         if (s != 0)
 281             handle_error_en(s, "pthread_attr_setstack");
 282     }
 283
 284     s = pthread_create(&thr, attrp, &thread_start, NULL);
 285     if (s != 0)
 286         handle_error_en(s, "pthread_create");
 287
 288     if (attrp != NULL) {
 289         s = pthread_attr_destroy(attrp);
 290         if (s != 0)
 291             handle_error_en(s, "pthread_attr_destroy");
 292     }
 293
 294     pause();    /* Terminates when other thread calls exit() */
 295 }
 296 .fi
 297 .SH SEE ALSO
 298 .ad l
 299 .nh
 300 .BR pthread_attr_setaffinity_np (3),
 301 .BR pthread_attr_setdetachstate (3),
 302 .BR pthread_attr_setguardsize (3),
 303 .BR pthread_attr_setinheritsched (3),
 304 .BR pthread_attr_setschedparam (3),
 305 .BR pthread_attr_setschedpolicy (3),
 306 .BR pthread_attr_setscope (3),
 307 .BR pthread_attr_setstack (3),
 308 .BR pthread_attr_setstackaddr (3),
 309 .BR pthread_attr_setstacksize (3),
 310 .BR pthread_create (3),
 311 .BR pthread_getattr_np (3),
 312 .BR pthreads (7)