original/man3/pthread_attr_init.3

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