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