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