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