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