original/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 .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 upward 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 nonzero 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 can 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 nonstandard GNU extension;
  97 hence the suffix "_np" (nonportable) in the name.
  98 .SH EXAMPLE
  99 The program below demonstrates the use of
 100 .BR pthread_getattr_np ().
 101 The program creates a thread that then uses
 102 .BR pthread_getattr_np ()
 103 to retrieve and display its guard size, stack address,
 104 and stack size attributes.
 105 Command-line arguments can be used to set these attributes
 106 to values other than the default when creating the thread.
 107 The shell sessions below demonstrate the use of the program.
 108
 109 In the first run, on an x86-32 system,
 110 a thread is created using default attributes:
 111
 112 .in +4n
 113 .nf
 114 .RB "$" " ulimit \-s" "      # No stack limit ==> default stack size is 2MB"
 115 unlimited
 116 .RB "$" " ./a.out"
 117 Attributes of created thread:
 118         Guard size          = 4096 bytes
 119         Stack address       = 0x40196000 (EOS = 0x40397000)
 120         Stack size          = 0x201000 (2101248) bytes
 121 .fi
 122 .in
 123
 124 In the following run, we see that if a guard size is specified,
 125 it is rounded up to the next multiple of the system page size
 126 (4096 bytes on x86-32):
 127
 128 .in +4n
 129 .nf
 130 .RB "$" " ./a.out \-g 4097"
 131 Thread attributes object after initializations:
 132         Guard size          = 4097 bytes
 133         Stack address       = (nil)
 134         Stack size          = 0x0 (0) bytes
 135
 136 Attributes of created thread:
 137         Guard size          = 8192 bytes
 138         Stack address       = 0x40196000 (EOS = 0x40397000)
 139         Stack size          = 0x201000 (2101248) bytes
 140 .fi
 141 .in
 142 .\".in +4n
 143 .\".nf
 144 .\"$ ./a.out \-s 0x8000
 145 .\"Thread attributes object after initializations:
 146 .\"        Guard size          = 4096 bytes
 147 .\"        Stack address       = 0xffff8000 (EOS = (nil))
 148 .\"        Stack size          = 0x8000 (32768) bytes
 149 .\"
 150 .\"Attributes of created thread:
 151 .\"        Guard size          = 4096 bytes
 152 .\"        Stack address       = 0x4001e000 (EOS = 0x40026000)
 153 .\"        Stack size          = 0x8000 (32768) bytes
 154 .\".fi
 155 .\".in
 156
 157 In the last run, the program manually allocates a stack for the thread.
 158 In this case, the guard size attribute is ignored.
 159
 160 .in +4n
 161 .nf
 162 .RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a"
 163 Allocated thread stack at 0x804d000
 164
 165 Thread attributes object after initializations:
 166         Guard size          = 4096 bytes
 167         Stack address       = 0x804d000 (EOS = 0x8055000)
 168         Stack size          = 0x8000 (32768) bytes
 169
 170 Attributes of created thread:
 171         Guard size          = 0 bytes
 172         Stack address       = 0x804d000 (EOS = 0x8055000)
 173         Stack size          = 0x8000 (32768) bytes
 174 .fi
 175 .in
 176 .SS Program source
 177 \&
 178 .nf
 179 #define _GNU_SOURCE     /* To get pthread_getattr_np() declaration */
 180 #include <pthread.h>
 181 #include <stdio.h>
 182 #include <stdlib.h>
 183 #include <unistd.h>
 184 #include <errno.h>
 185
 186 #define handle_error_en(en, msg) \\
 187         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 188
 189 static void
 190 display_stack_related_attributes(pthread_attr_t *attr, char *prefix)
 191 {
 192     int s;
 193     size_t stack_size, guard_size;
 194     void *stack_addr;
 195
 196     s = pthread_attr_getguardsize(attr, &guard_size);
 197     if (s != 0)
 198         handle_error_en(s, "pthread_attr_getguardsize");
 199     printf("%sGuard size          = %d bytes\\n", prefix, guard_size);
 200
 201     s = pthread_attr_getstack(attr, &stack_addr, &stack_size);
 202     if (s != 0)
 203         handle_error_en(s, "pthread_attr_getstack");
 204     printf("%sStack address       = %p", prefix, stack_addr);
 205     if (stack_size > 0)
 206         printf(" (EOS = %p)", (char *) stack_addr + stack_size);
 207     printf("\\n");
 208     printf("%sStack size          = 0x%x (%d) bytes\\n",
 209             prefix, stack_size, stack_size);
 210 }
 211
 212 static void
 213 display_thread_attributes(pthread_t thread, char *prefix)
 214 {
 215     int s;
 216     pthread_attr_t attr;
 217
 218     s = pthread_getattr_np(thread, &attr);
 219     if (s != 0)
 220         handle_error_en(s, "pthread_getattr_np");
 221
 222     display_stack_related_attributes(&attr, prefix);
 223
 224     s = pthread_attr_destroy(&attr);
 225     if (s != 0)
 226         handle_error_en(s, "pthread_attr_destroy");
 227 }
 228
 229 static void *           /* Start function for thread we create */
 230 thread_start(void *arg)
 231 {
 232     printf("Attributes of created thread:\\n");
 233     display_thread_attributes(pthread_self(), "\\t");
 234
 235     exit(EXIT_SUCCESS);         /* Terminate all threads */
 236 }
 237
 238 static void
 239 usage(char *pname, char *msg)
 240 {
 241     if (msg != NULL)
 242         fputs(msg, stderr);
 243     fprintf(stderr, "Usage: %s [\-s stack-size [\-a]]"
 244             " [\-g guard-size]\\n", pname);
 245     fprintf(stderr, "\\t\\t\-a means program should allocate stack\\n");
 246     exit(EXIT_FAILURE);
 247 }
 248
 249 static pthread_attr_t *   /* Get thread attributes from command line */
 250 get_thread_attributes_from_cl(int argc, char *argv[],
 251                               pthread_attr_t *attrp)
 252 {
 253     int s, opt, allocate_stack;
 254     long stack_size, guard_size;
 255             void *stack_addr;
 256     pthread_attr_t *ret_attrp = NULL;   /* Set to attrp if we initialize
 257                                            a thread attributes object */
 258     allocate_stack = 0;
 259     stack_size = \-1;
 260     guard_size = \-1;
 261
 262     while ((opt = getopt(argc, argv, "ag:s:")) != \-1) {
 263         switch (opt) {
 264         case \(aqa\(aq:   allocate_stack = 1;                     break;
 265         case \(aqg\(aq:   guard_size = strtoul(optarg, NULL, 0);  break;
 266         case \(aqs\(aq:   stack_size = strtoul(optarg, NULL, 0);  break;
 267         default:    usage(argv[0], NULL);
 268         }
 269     }
 270
 271     if (allocate_stack && stack_size == \-1)
 272         usage(argv[0], "Specifying \-a without \-s makes no sense\\n");
 273
 274     if (argc > optind)
 275         usage(argv[0], "Extraneous command\-line arguments\\n");
 276
 277     if (stack_size >= 0 || guard_size > 0) {
 278         ret_attrp = attrp;
 279
 280         s = pthread_attr_init(attrp);
 281         if (s != 0)
 282             handle_error_en(s, "pthread_attr_init");
 283     }
 284
 285     if (stack_size >= 0) {
 286         if (!allocate_stack) {
 287             s = pthread_attr_setstacksize(attrp, stack_size);
 288             if (s != 0)
 289                 handle_error_en(s, "pthread_attr_setstacksize");
 290         } else {
 291             s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE),
 292                                stack_size);
 293             if (s != 0)
 294                 handle_error_en(s, "posix_memalign");
 295             printf("Allocated thread stack at %p\\n\\n", stack_addr);
 296
 297             s = pthread_attr_setstack(attrp, stack_addr, stack_size);
 298             if (s != 0)
 299                 handle_error_en(s, "pthread_attr_setstacksize");
 300         }
 301     }
 302
 303     if (guard_size >= 0) {
 304         s = pthread_attr_setguardsize(attrp, guard_size);
 305         if (s != 0)
 306             handle_error_en(s, "pthread_attr_setstacksize");
 307     }
 308
 309     return ret_attrp;
 310 }
 311
 312 int
 313 main(int argc, char *argv[])
 314 {
 315     int s;
 316     pthread_t thr;
 317     pthread_attr_t attr;
 318     pthread_attr_t *attrp = NULL;    /* Set to &attr if we initialize
 319                                         a thread attributes object */
 320
 321     attrp = get_thread_attributes_from_cl(argc, argv, &attr);
 322
 323     if (attrp != NULL) {
 324         printf("Thread attributes object after initializations:\\n");
 325         display_stack_related_attributes(attrp, "\\t");
 326         printf("\\n");
 327     }
 328
 329     s = pthread_create(&thr, attrp, &thread_start, NULL);
 330     if (s != 0)
 331         handle_error_en(s, "pthread_create");
 332
 333     if (attrp != NULL) {
 334         s = pthread_attr_destroy(attrp);
 335         if (s != 0)
 336             handle_error_en(s, "pthread_attr_destroy");
 337     }
 338
 339     pause();    /* Terminates when other thread calls exit() */
 340 }
 341 .fi
 342 .SH SEE ALSO
 343 .BR pthread_attr_getaffinity_np (3),
 344 .BR pthread_attr_getdetachstate (3),
 345 .BR pthread_attr_getguardsize (3),
 346 .BR pthread_attr_getinheritsched (3),
 347 .BR pthread_attr_getschedparam (3),
 348 .BR pthread_attr_getschedpolicy (3),
 349 .BR pthread_attr_getscope (3),
 350 .BR pthread_attr_getstack (3),
 351 .BR pthread_attr_getstackaddr (3),
 352 .BR pthread_attr_getstacksize (3),
 353 .BR pthread_attr_init (3),
 354 .BR pthread_create (3),
 355 .BR pthreads (7)