man3/pthread_attr_setstacksize.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH PTHREAD_ATTR_SETSTACKSIZE 3 2021-03-22 "Linux" "Linux Programmer's Manual"
   7 .SH NAME
   8 pthread_attr_setstacksize, pthread_attr_getstacksize \- set/get stack size
   9 attribute in thread attributes object
  10 .SH LIBRARY
  11 POSIX threads library
  12 .RI ( libpthread ", " \-lpthread )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <pthread.h>
  16 .PP
  17 .BI "int pthread_attr_setstacksize(pthread_attr_t *" attr \
  18 ", size_t " stacksize );
  19 .BI "int pthread_attr_getstacksize(const pthread_attr_t *restrict " attr ,
  20 .BI "                              size_t *restrict " stacksize );
  21 .fi
  22 .SH DESCRIPTION
  23 The
  24 .BR pthread_attr_setstacksize ()
  25 function sets the stack size attribute of the
  26 thread attributes object referred to by
  27 .I attr
  28 to the value specified in
  29 .IR stacksize .
  30 .PP
  31 The stack size attribute determines the minimum size (in bytes) that
  32 will be allocated for threads created using the thread attributes object
  33 .IR attr .
  34 .PP
  35 The
  36 .BR pthread_attr_getstacksize ()
  37 function returns the stack size attribute of the
  38 thread attributes object referred to by
  39 .I attr
  40 in the buffer pointed to by
  41 .IR stacksize .
  42 .SH RETURN VALUE
  43 On success, these functions return 0;
  44 on error, they return a nonzero error number.
  45 .SH ERRORS
  46 .BR pthread_attr_setstacksize ()
  47 can fail with the following error:
  48 .TP
  49 .B EINVAL
  50 The stack size is less than
  51 .BR PTHREAD_STACK_MIN
  52 (16384) bytes.
  53 .PP
  54 On some systems,
  55 .\" e.g., MacOS
  56 .BR pthread_attr_setstacksize ()
  57 can fail with the error
  58 .B EINVAL
  59 if
  60 .I stacksize
  61 is not a multiple of the system page size.
  62 .SH VERSIONS
  63 These functions are provided by glibc since version 2.1.
  64 .SH ATTRIBUTES
  65 For an explanation of the terms used in this section, see
  66 .BR attributes (7).
  67 .ad l
  68 .nh
  69 .TS
  70 allbox;
  71 lbx lb lb
  72 l l l.
  73 Interface       Attribute       Value
  74 T{
  75 .BR pthread_attr_setstacksize (),
  76 .BR pthread_attr_getstacksize ()
  77 T}      Thread safety   MT-Safe
  78 .TE
  79 .hy
  80 .ad
  81 .sp 1
  82 .SH CONFORMING TO
  83 POSIX.1-2001, POSIX.1-2008.
  84 .SH NOTES
  85 For details on the default stack size of new threads, see
  86 .BR pthread_create (3).
  87 .PP
  88 A thread's stack size is fixed at the time of thread creation.
  89 Only the main thread can dynamically grow its stack.
  90 .PP
  91 The
  92 .BR pthread_attr_setstack (3)
  93 function allows an application to set both the size and location
  94 of a caller-allocated stack that is to be used by a thread.
  95 .SH BUGS
  96 As at glibc 2.8,
  97 if the specified
  98 .I stacksize
  99 is not a multiple of
 100 .BR STACK_ALIGN
 101 (16 bytes on most architectures), it may be rounded
 102 .IR downward ,
 103 in violation of POSIX.1, which says that the allocated stack will
 104 be at least
 105 .I stacksize
 106 bytes.
 107 .SH EXAMPLES
 108 See
 109 .BR pthread_create (3).
 110 .SH SEE ALSO
 111 .BR getrlimit (2),
 112 .BR pthread_attr_init (3),
 113 .BR pthread_attr_setguardsize (3),
 114 .BR pthread_attr_setstack (3),
 115 .BR pthread_create (3),
 116 .BR pthreads (7)