man3/pthread_attr_init.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH PTHREAD_ATTR_INIT 3 2021-03-22 "Linux" "Linux Programmer's Manual"
   7 .SH NAME
   8 pthread_attr_init, pthread_attr_destroy \- initialize and destroy
   9 thread attributes object
  10 .SH LIBRARY
  11 POSIX threads library
  12 .RI ( libpthread ", " \-lpthread )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <pthread.h>
  16 .PP
  17 .BI "int pthread_attr_init(pthread_attr_t *" attr );
  18 .BI "int pthread_attr_destroy(pthread_attr_t *" attr );
  19 .fi
  20 .SH DESCRIPTION
  21 The
  22 .BR pthread_attr_init ()
  23 function initializes the thread attributes object pointed to by
  24 .I attr
  25 with default attribute values.
  26 After this call, individual attributes of the object can be set
  27 using various related functions (listed under SEE ALSO),
  28 and then the object can be used in one or more
  29 .BR pthread_create (3)
  30 calls that create threads.
  31 .PP
  32 Calling
  33 .BR pthread_attr_init ()
  34 on a thread attributes object that has already been initialized
  35 results in undefined behavior.
  36 .PP
  37 When a thread attributes object is no longer required,
  38 it should be destroyed using the
  39 .BR pthread_attr_destroy ()
  40 function.
  41 Destroying a thread attributes object has no effect
  42 on threads that were created using that object.
  43 .PP
  44 Once a thread attributes object has been destroyed,
  45 it can be reinitialized using
  46 .BR pthread_attr_init ().
  47 Any other use of a destroyed thread attributes object
  48 has undefined results.
  49 .SH RETURN VALUE
  50 On success, these functions return 0;
  51 on error, they return a nonzero error number.
  52 .SH ERRORS
  53 POSIX.1 documents an
  54 .B ENOMEM
  55 error for
  56 .BR pthread_attr_init ();
  57 on Linux these functions always succeed
  58 (but portable and future-proof applications should nevertheless
  59 handle a possible error return).
  60 .SH ATTRIBUTES
  61 For an explanation of the terms used in this section, see
  62 .BR attributes (7).
  63 .ad l
  64 .nh
  65 .TS
  66 allbox;
  67 lbx lb lb
  68 l l l.
  69 Interface       Attribute       Value
  70 T{
  71 .BR pthread_attr_init (),
  72 .BR pthread_attr_destroy ()
  73 T}      Thread safety   MT-Safe
  74 .TE
  75 .hy
  76 .ad
  77 .sp 1
  78 .SH CONFORMING TO
  79 POSIX.1-2001, POSIX.1-2008.
  80 .SH NOTES
  81 The
  82 .I pthread_attr_t
  83 type should be treated as opaque:
  84 any access to the object other than via pthreads functions
  85 is nonportable and produces undefined results.
  86 .SH EXAMPLES
  87 The program below optionally makes use of
  88 .BR pthread_attr_init ()
  89 and various related functions to initialize a thread attributes
  90 object that is used to create a single thread.
  91 Once created, the thread uses the
  92 .BR pthread_getattr_np (3)
  93 function (a nonstandard GNU extension) to retrieve the thread's
  94 attributes, and then displays those attributes.
  95 .PP
  96 If the program is run with no command-line argument,
  97 then it passes NULL as the
  98 .I attr
  99 argument of
 100 .BR pthread_create (3),
 101 so that the thread is created with default attributes.
 102 Running the program on Linux/x86-32 with the NPTL threading implementation,
 103 we see the following:
 104 .PP
 105 .in +4n
 106 .EX
 107 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
 108 .RB "$" " ulimit \-s" "       # No stack limit ==> default stack size is 2 MB"
 109 unlimited
 110 .RB "$" " ./a.out"
 111 Thread attributes:
 112         Detach state        = PTHREAD_CREATE_JOINABLE
 113         Scope               = PTHREAD_SCOPE_SYSTEM
 114         Inherit scheduler   = PTHREAD_INHERIT_SCHED
 115         Scheduling policy   = SCHED_OTHER
 116         Scheduling priority = 0
 117         Guard size          = 4096 bytes
 118         Stack address       = 0x40196000
 119         Stack size          = 0x201000 bytes
 120 .EE
 121 .in
 122 .PP
 123 When we supply a stack size as a command-line argument,
 124 the program initializes a thread attributes object,
 125 sets various attributes in that object,
 126 and passes a pointer to the object in the call to
 127 .BR pthread_create (3).
 128 Running the program on Linux/x86-32 with the NPTL threading implementation,
 129 we see the following:
 130 .PP
 131 .in +4n
 132 .EX
 133 .\" Results from glibc 2.8, SUSE 11.0; Oct 2008
 134 .RB "$" " ./a.out 0x3000000"
 135 posix_memalign() allocated at 0x40197000
 136 Thread attributes:
 137         Detach state        = PTHREAD_CREATE_DETACHED
 138         Scope               = PTHREAD_SCOPE_SYSTEM
 139         Inherit scheduler   = PTHREAD_EXPLICIT_SCHED
 140         Scheduling policy   = SCHED_OTHER
 141         Scheduling priority = 0
 142         Guard size          = 0 bytes
 143         Stack address       = 0x40197000
 144         Stack size          = 0x3000000 bytes
 145 .EE
 146 .in
 147 .SS Program source
 148 \&
 149 .EX
 150 #define _GNU_SOURCE     /* To get pthread_getattr_np() declaration */
 151 #include <pthread.h>
 152 #include <stdio.h>
 153 #include <stdlib.h>
 154 #include <unistd.h>
 155 #include <errno.h>
 156
 157 #define handle_error_en(en, msg) \e
 158         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 159
 160 static void
 161 display_pthread_attr(pthread_attr_t *attr, char *prefix)
 162 {
 163     int s, i;
 164     size_t v;
 165     void *stkaddr;
 166     struct sched_param sp;
 167
 168     s = pthread_attr_getdetachstate(attr, &i);
 169     if (s != 0)
 170         handle_error_en(s, "pthread_attr_getdetachstate");
 171     printf("%sDetach state        = %s\en", prefix,
 172             (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :
 173             (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :
 174             "???");
 175
 176     s = pthread_attr_getscope(attr, &i);
 177     if (s != 0)
 178         handle_error_en(s, "pthread_attr_getscope");
 179     printf("%sScope               = %s\en", prefix,
 180             (i == PTHREAD_SCOPE_SYSTEM)  ? "PTHREAD_SCOPE_SYSTEM" :
 181             (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :
 182             "???");
 183
 184     s = pthread_attr_getinheritsched(attr, &i);
 185     if (s != 0)
 186         handle_error_en(s, "pthread_attr_getinheritsched");
 187     printf("%sInherit scheduler   = %s\en", prefix,
 188             (i == PTHREAD_INHERIT_SCHED)  ? "PTHREAD_INHERIT_SCHED" :
 189             (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :
 190             "???");
 191
 192     s = pthread_attr_getschedpolicy(attr, &i);
 193     if (s != 0)
 194         handle_error_en(s, "pthread_attr_getschedpolicy");
 195     printf("%sScheduling policy   = %s\en", prefix,
 196             (i == SCHED_OTHER) ? "SCHED_OTHER" :
 197             (i == SCHED_FIFO)  ? "SCHED_FIFO" :
 198             (i == SCHED_RR)    ? "SCHED_RR" :
 199             "???");
 200
 201     s = pthread_attr_getschedparam(attr, &sp);
 202     if (s != 0)
 203         handle_error_en(s, "pthread_attr_getschedparam");
 204     printf("%sScheduling priority = %d\en", prefix, sp.sched_priority);
 205
 206     s = pthread_attr_getguardsize(attr, &v);
 207     if (s != 0)
 208         handle_error_en(s, "pthread_attr_getguardsize");
 209     printf("%sGuard size          = %zu bytes\en", prefix, v);
 210
 211     s = pthread_attr_getstack(attr, &stkaddr, &v);
 212     if (s != 0)
 213         handle_error_en(s, "pthread_attr_getstack");
 214     printf("%sStack address       = %p\en", prefix, stkaddr);
 215     printf("%sStack size          = %#zx bytes\en", prefix, v);
 216 }
 217
 218 static void *
 219 thread_start(void *arg)
 220 {
 221     int s;
 222     pthread_attr_t gattr;
 223
 224     /* pthread_getattr_np() is a non\-standard GNU extension that
 225        retrieves the attributes of the thread specified in its
 226        first argument. */
 227
 228     s = pthread_getattr_np(pthread_self(), &gattr);
 229     if (s != 0)
 230         handle_error_en(s, "pthread_getattr_np");
 231
 232     printf("Thread attributes:\en");
 233     display_pthread_attr(&gattr, "\et");
 234
 235     exit(EXIT_SUCCESS);         /* Terminate all threads */
 236 }
 237
 238 int
 239 main(int argc, char *argv[])
 240 {
 241     pthread_t thr;
 242     pthread_attr_t attr;
 243     pthread_attr_t *attrp;      /* NULL or &attr */
 244     int s;
 245
 246     attrp = NULL;
 247
 248     /* If a command\-line argument was supplied, use it to set the
 249        stack\-size attribute and set a few other thread attributes,
 250        and set attrp pointing to thread attributes object. */
 251
 252     if (argc > 1) {
 253         size_t stack_size;
 254         void *sp;
 255
 256         attrp = &attr;
 257
 258         s = pthread_attr_init(&attr);
 259         if (s != 0)
 260             handle_error_en(s, "pthread_attr_init");
 261
 262         s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
 263         if (s != 0)
 264             handle_error_en(s, "pthread_attr_setdetachstate");
 265
 266         s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
 267         if (s != 0)
 268             handle_error_en(s, "pthread_attr_setinheritsched");
 269
 270         stack_size = strtoul(argv[1], NULL, 0);
 271
 272         s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);
 273         if (s != 0)
 274             handle_error_en(s, "posix_memalign");
 275
 276         printf("posix_memalign() allocated at %p\en", sp);
 277
 278         s = pthread_attr_setstack(&attr, sp, stack_size);
 279         if (s != 0)
 280             handle_error_en(s, "pthread_attr_setstack");
 281     }
 282
 283     s = pthread_create(&thr, attrp, &thread_start, NULL);
 284     if (s != 0)
 285         handle_error_en(s, "pthread_create");
 286
 287     if (attrp != NULL) {
 288         s = pthread_attr_destroy(attrp);
 289         if (s != 0)
 290             handle_error_en(s, "pthread_attr_destroy");
 291     }
 292
 293     pause();    /* Terminates when other thread calls exit() */
 294 }
 295 .EE
 296 .SH SEE ALSO
 297 .ad l
 298 .nh
 299 .BR pthread_attr_setaffinity_np (3),
 300 .BR pthread_attr_setdetachstate (3),
 301 .BR pthread_attr_setguardsize (3),
 302 .BR pthread_attr_setinheritsched (3),
 303 .BR pthread_attr_setschedparam (3),
 304 .BR pthread_attr_setschedpolicy (3),
 305 .BR pthread_attr_setscope (3),
 306 .BR pthread_attr_setsigmask_np (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 pthread_setattr_default_np (3),
 313 .BR pthreads (7)