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