man3/pthread_getattr_np.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_GETATTR_NP 3 2008-10-24 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 pthread_getattr_np \- get attributes of created thread
  27 .SH SYNOPSIS
  28 .nf
  29 .B #define _GNU_SOURCE
  30 .B #include <pthread.h>
  31
  32 .BI "int pthread_getattr_np(pthread_t " thread ", pthread_attr_t *" attr );
  33 .sp
  34 Compile and link with \fI\-pthread\fP.
  35 .SH DESCRIPTION
  36 The
  37 .BR pthread_getattr_np ()
  38 function initializes the thread attributes object referred to by
  39 .I attr
  40 so that it contains actual attribute values describing the running thread
  41 .IR thread .
  42
  43 The returned attribute values may differ from
  44 the corresponding attribute values passed in the
  45 .I attr
  46 object that was used to create the thread using
  47 .BR pthread_create (3).
  48 In particular, the following attributes may differ:
  49 .IP * 2
  50 the detach state, since a joinable thread may have detached itself
  51 after creation;
  52 .IP *
  53 the stack size,
  54 which the implementation may align to a suitable boundary.
  55 .IP *
  56 and the guard size,
  57 which the implementation may round upwards to a multiple of the page size,
  58 or ignore (i.e., treat as 0),
  59 if the application is allocating its own stack.
  60 .PP
  61 Furthermore, if the stack address attribute was not set
  62 in the thread attributes object used to create the thread,
  63 then the returned thread attributes object will report the actual
  64 stack address that the implementation selected for the thread.
  65
  66 When the thread attributes object returned by
  67 .BR pthread_getattr_np ()
  68 is no longer required, it should be destroyed using
  69 .BR pthread_attr_destroy (3).
  70 .SH RETURN VALUE
  71 On success, this function returns 0;
  72 on error, it returns a non-zero error number.
  73 .SH ERRORS
  74 .TP
  75 .B ENOMEM
  76 .\" Can happen (but unlikely) while trying to allocate memory for cpuset
  77 Insufficient memory.
  78 .PP
  79 In addition, if
  80 .I thread
  81 refers to the main thread, then
  82 .BR pthread_getattr_np ()
  83 may fail because of errors from various underlying calls:
  84 .BR fopen (3),
  85 if
  86 .IR /proc/self/maps
  87 can't be opened;
  88 and
  89 .BR getrlimit (2),
  90 if the
  91 .BR RLIMIT_STACK
  92 resource limit is not supported.
  93 .SH VERSIONS
  94 This function is available in glibc since version 2.2.3.
  95 .SH CONFORMING TO
  96 This function is a non-standard GNU extension.
  97 .SH EXAMPLE
  98 The program below demonstrates the use of
  99 .BR pthread_getattr_np ().
 100 The program creates a thread that then uses
 101 .BR pthread_getattr_np ()
 102 to retrieve and display its guard size, stack address,
 103 and stack size attributes.
 104 Command-line arguments can be used to set these attributes
 105 to values other than the default when creating the thread.
 106 The shell sessions below demonstrate the use of the program.
 107
 108 In the first run, on an x86-32 system,
 109 a thread is created using default attributes:
 110
 111 .in +4n
 112 .nf
 113 .RB "$" " ulimit \-s" "      # No stack imit ==> default stack size is 2MB"
 114 unlimited
 115 .RB "$" " ./a.out"
 116 Attributes of created thread:
 117         Guard size          = 4096 bytes
 118         Stack address       = 0x40196000 (EOS = 0x40397000)
 119         Stack size          = 0x201000 (2101248) bytes
 120 .fi
 121 .in
 122
 123 In the following run, we see that if a guard size is specified,
 124 it is rounded up to the next multiple of the system page size
 125 (4096 bytes on x86-32):
 126
 127 .in +4n
 128 .nf
 129 .RB "$" " ./a.out \-g 4097"
 130 Thread attributes object after initializations:
 131         Guard size          = 4097 bytes
 132         Stack address       = (nil)
 133         Stack size          = 0x0 (0) bytes
 134
 135 Attributes of created thread:
 136         Guard size          = 8192 bytes
 137         Stack address       = 0x40196000 (EOS = 0x40397000)
 138         Stack size          = 0x201000 (2101248) bytes
 139 .fi
 140 .in
 141 .\".in +4n
 142 .\".nf
 143 .\"$ ./a.out \-s 0x8000
 144 .\"Thread attributes object after initializations:
 145 .\"        Guard size          = 4096 bytes
 146 .\"        Stack address       = 0xffff8000 (EOS = (nil))
 147 .\"        Stack size          = 0x8000 (32768) bytes
 148 .\"
 149 .\"Attributes of created thread:
 150 .\"        Guard size          = 4096 bytes
 151 .\"        Stack address       = 0x4001e000 (EOS = 0x40026000)
 152 .\"        Stack size          = 0x8000 (32768) bytes
 153 .\".fi
 154 .\".in
 155
 156 In the last run, the program manually allocates a stack for the thread.
 157 In this case, the guard size attribute is ignored.
 158
 159 .in +4n
 160 .nf
 161 .RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a"
 162 Allocated thread stack at 0x804d000
 163
 164 Thread attributes object after initializations:
 165         Guard size          = 4096 bytes
 166         Stack address       = 0x804d000 (EOS = 0x8055000)
 167         Stack size          = 0x8000 (32768) bytes
 168
 169 Attributes of created thread:
 170         Guard size          = 0 bytes
 171         Stack address       = 0x804d000 (EOS = 0x8055000)
 172         Stack size          = 0x8000 (32768) bytes
 173 .fi
 174 .in
 175
 176 .nf
 177 #define _GNU_SOURCE     /* To get pthread_getattr_np() declaration */
 178 #include <pthread.h>
 179 #include <stdio.h>
 180 #include <stdlib.h>
 181 #include <unistd.h>
 182 #include <errno.h>
 183
 184 #define errExitEN(en, msg)      { errno = en; perror(msg); \\
 185                                   exit(EXIT_FAILURE); }
 186
 187 static void
 188 display_stack_related_attributes(pthread_attr_t *attr, char *prefix)
 189 {
 190     int s;
 191     size_t stack_size, guard_size;
 192     void *stack_addr;
 193
 194     s = pthread_attr_getguardsize(attr, &guard_size);
 195     if (s != 0)
 196         errExitEN(s, "pthread_attr_getguardsize");
 197     printf("%sGuard size          = %d bytes\\n", prefix, guard_size);
 198
 199     s = pthread_attr_getstack(attr, &stack_addr, &stack_size);
 200     if (s != 0)
 201         errExitEN(s, "pthread_attr_getstack");
 202     printf("%sStack address       = %p", prefix, stack_addr);
 203     if (stack_size > 0)
 204         printf(" (EOS = %p)", (char *) stack_addr + stack_size);
 205     printf("\\n");
 206     printf("%sStack size          = 0x%x (%d) bytes\\n",
 207             prefix, stack_size, stack_size);
 208 }
 209
 210 static void
 211 display_thread_attributes(pthread_t thread, char *prefix)
 212 {
 213     int s;
 214     pthread_attr_t attr;
 215
 216     s = pthread_getattr_np(thread, &attr);
 217     if (s != 0)
 218         errExitEN(s, "pthread_getattr_np");
 219
 220     display_stack_related_attributes(&attr, prefix);
 221
 222     s = pthread_attr_destroy(&attr);
 223     if (s != 0)
 224         errExitEN(s, "pthread_attr_destroy");
 225 }
 226
 227 static void *           /* Start function for thread we create */
 228 thread_start(void *arg)
 229 {
 230     printf("Attributes of created thread:\\n");
 231     display_thread_attributes(pthread_self(), "\\t");
 232
 233     exit(EXIT_SUCCESS);         /* Terminate all threads */
 234 }
 235
 236 static void
 237 usage(char *pname, char *msg)
 238 {
 239     if (msg != NULL)
 240         fputs(msg, stderr);
 241     fprintf(stderr, "Usage: %s [\-s stack-size [-a]]"
 242             " [\-g guard-size]\\n", pname);
 243     fprintf(stderr, "\\t\\t\-a means program should allocate stack\\n");
 244     exit(EXIT_FAILURE);
 245 }
 246
 247 static pthread_attr_t *   /* Get thread attributes from command line */
 248 get_thread_attributes_from_cl(int argc, char *argv[],
 249                               pthread_attr_t *attrp)
 250 {
 251     int s, opt, allocate_stack;
 252     long stack_size, guard_size;
 253             void *stack_addr;
 254     pthread_attr_t *ret_attrp = NULL;   /* Set to attrp if we initialize
 255                                            a thread attributes object */
 256     allocate_stack = 0;
 257     stack_size = \-1;
 258     guard_size = \-1;
 259
 260     while ((opt = getopt(argc, argv, "ag:s:")) != \-1) {
 261         switch (opt) {
 262         case \(aqa':   allocate_stack = 1;                     break;
 263         case \(aqg':   guard_size = strtoul(optarg, NULL, 0);  break;
 264         case \(aqs':   stack_size = strtoul(optarg, NULL, 0);  break;
 265         default:    usage(argv[0], NULL);
 266         }
 267     }
 268
 269     if (allocate_stack && stack_size == \-1)
 270         usage(argv[0], "Specifying \-a without -s makes no sense\\n");
 271
 272     if (argc > optind)
 273         usage(argv[0], "Extraneous command\-line arguments\\n");
 274
 275     if (stack_size >= 0 || guard_size > 0) {
 276         ret_attrp = attrp;
 277
 278         s = pthread_attr_init(attrp);
 279         if (s != 0)
 280             errExitEN(s, "pthread_attr_init");
 281     }
 282
 283     if (stack_size >= 0) {
 284         if (!allocate_stack) {
 285             s = pthread_attr_setstacksize(attrp, stack_size);
 286             if (s != 0)
 287                 errExitEN(s, "pthread_attr_setstacksize");
 288         } else {
 289             s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE),
 290                                stack_size);
 291             if (s != 0)
 292                 errExitEN(s, "posix_memalign");
 293             printf("Allocated thread stack at %p\\n\\n", stack_addr);
 294
 295             s = pthread_attr_setstack(attrp, stack_addr, stack_size);
 296             if (s != 0)
 297                 errExitEN(s, "pthread_attr_setstacksize");
 298         }
 299     }
 300
 301     if (guard_size >= 0) {
 302         s = pthread_attr_setguardsize(attrp, guard_size);
 303         if (s != 0)
 304             errExitEN(s, "pthread_attr_setstacksize");
 305     }
 306
 307     return ret_attrp;
 308 }
 309
 310 int
 311 main(int argc, char *argv[])
 312 {
 313     int s;
 314     pthread_t thr;
 315     pthread_attr_t attr;
 316     pthread_attr_t *attrp = NULL;    /* Set to &attr if we initialize
 317                                         a thread attributes object */
 318
 319     attrp = get_thread_attributes_from_cl(argc, argv, &attr);
 320
 321     if (attrp != NULL) {
 322         printf("Thread attributes object after initializations:\\n");
 323         display_stack_related_attributes(attrp, "\\t");
 324         printf("\\n");
 325     }
 326
 327     s = pthread_create(&thr, attrp, &thread_start, NULL);
 328     if (s != 0)
 329         errExitEN(s, "pthread_create");
 330
 331     if (attrp != NULL) {
 332         s = pthread_attr_destroy(attrp);
 333         if (s != 0)
 334             errExitEN(s, "pthread_attr_destroy");
 335     }
 336
 337     pause();    /* Terminates when other thread calls exit() */
 338 }
 339 .fi
 340 .SH SEE ALSO
 341 .BR pthread_attr_getaffinity_np (3),
 342 .BR pthread_attr_getdetachstate (3),
 343 .BR pthread_attr_getguardsize (3),
 344 .BR pthread_attr_getinheritsched (3),
 345 .BR pthread_attr_getschedparam (3),
 346 .BR pthread_attr_getschedpolicy (3),
 347 .BR pthread_attr_getscope (3),
 348 .BR pthread_attr_getstack (3),
 349 .BR pthread_attr_getstackaddr (3),
 350 .BR pthread_attr_getstacksize (3),
 351 .BR pthread_attr_init (3),
 352 .BR pthread_create (3),
 353 .BR pthreads (7)