man3/pthread_attr_setguardsize.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_setguardsize 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 pthread_attr_setguardsize, pthread_attr_getguardsize \- set/get guard 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_setguardsize(pthread_attr_t *" attr \
  18 ", size_t " guardsize );
  19 .BI "int pthread_attr_getguardsize(const pthread_attr_t *restrict " attr ,
  20 .BI "                              size_t *restrict " guardsize );
  21 .fi
  22 .SH DESCRIPTION
  23 The
  24 .BR pthread_attr_setguardsize ()
  25 function sets the guard size attribute of the
  26 thread attributes object referred to by
  27 .I attr
  28 to the value specified in
  29 .IR guardsize .
  30 .PP
  31 If
  32 .I guardsize
  33 is greater than 0,
  34 then for each new thread created using
  35 .I attr
  36 the system allocates an additional region of at least
  37 .I guardsize
  38 bytes at the end of the thread's stack to act as the guard area
  39 for the stack (but see BUGS).
  40 .PP
  41 If
  42 .I guardsize
  43 is 0, then new threads created with
  44 .I attr
  45 will not have a guard area.
  46 .PP
  47 The default guard size is the same as the system page size.
  48 .PP
  49 If the stack address attribute has been set in
  50 .I attr
  51 (using
  52 .BR pthread_attr_setstack (3)
  53 or
  54 .BR pthread_attr_setstackaddr (3)),
  55 meaning that the caller is allocating the thread's stack,
  56 then the guard size attribute is ignored
  57 (i.e., no guard area is created by the system):
  58 it is the application's responsibility to handle stack overflow
  59 (perhaps by using
  60 .BR mprotect (2)
  61 to manually define a guard area at the end of the stack
  62 that it has allocated).
  63 .PP
  64 The
  65 .BR pthread_attr_getguardsize ()
  66 function returns the guard size attribute of the
  67 thread attributes object referred to by
  68 .I attr
  69 in the buffer pointed to by
  70 .IR guardsize .
  71 .SH RETURN VALUE
  72 On success, these functions return 0;
  73 on error, they return a nonzero error number.
  74 .SH ERRORS
  75 POSIX.1 documents an
  76 .B EINVAL
  77 error if
  78 .I attr
  79 or
  80 .I guardsize
  81 is invalid.
  82 On Linux these functions always succeed
  83 (but portable and future-proof applications should nevertheless
  84 handle a possible error return).
  85 .SH VERSIONS
  86 These functions are provided by glibc since version 2.1.
  87 .SH ATTRIBUTES
  88 For an explanation of the terms used in this section, see
  89 .BR attributes (7).
  90 .ad l
  91 .nh
  92 .TS
  93 allbox;
  94 lbx lb lb
  95 l l l.
  96 Interface       Attribute       Value
  97 T{
  98 .BR pthread_attr_setguardsize (),
  99 .BR pthread_attr_getguardsize ()
 100 T}      Thread safety   MT-Safe
 101 .TE
 102 .hy
 103 .ad
 104 .sp 1
 105 .SH STANDARDS
 106 POSIX.1-2001, POSIX.1-2008.
 107 .SH NOTES
 108 A guard area consists of virtual memory pages that are protected
 109 to prevent read and write access.
 110 If a thread overflows its stack into the guard area,
 111 then, on most hard architectures, it receives a
 112 .B SIGSEGV
 113 signal, thus notifying it of the overflow.
 114 Guard areas start on page boundaries,
 115 and the guard size is internally rounded up to
 116 the system page size when creating a thread.
 117 (Nevertheless,
 118 .BR pthread_attr_getguardsize ()
 119 returns the guard size that was set by
 120 .BR pthread_attr_setguardsize ().)
 121 .PP
 122 Setting a guard size of 0 may be useful to save memory
 123 in an application that creates many threads
 124 and knows that stack overflow can never occur.
 125 .PP
 126 Choosing a guard size larger than the default size
 127 may be necessary for detecting stack overflows
 128 if a thread allocates large data structures on the stack.
 129 .SH BUGS
 130 As at glibc 2.8, the NPTL threading implementation includes
 131 the guard area within the stack size allocation,
 132 rather than allocating extra space at the end of the stack,
 133 as POSIX.1 requires.
 134 (This can result in an
 135 .B EINVAL
 136 error from
 137 .BR pthread_create (3)
 138 if the guard size value is too large,
 139 leaving no space for the actual stack.)
 140 .PP
 141 The obsolete LinuxThreads implementation did the right thing,
 142 allocating extra space at the end of the stack for the guard area.
 143 .\" glibc includes the guardsize within the allocated stack size,
 144 .\" which looks pretty clearly to be in violation of POSIX.
 145 .\"
 146 .\" Filed bug, 22 Oct 2008:
 147 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6973
 148 .\"
 149 .\" Older reports:
 150 .\" https//bugzilla.redhat.com/show_bug.cgi?id=435337
 151 .\" Reportedly, LinuxThreads did the right thing, allocating
 152 .\" extra space at the end of the stack:
 153 .\" http://sourceware.org/ml/libc-alpha/2008-05/msg00086.html
 154 .SH EXAMPLES
 155 See
 156 .BR pthread_getattr_np (3).
 157 .SH SEE ALSO
 158 .BR mmap (2),
 159 .BR mprotect (2),
 160 .BR pthread_attr_init (3),
 161 .BR pthread_attr_setstack (3),
 162 .BR pthread_attr_setstacksize (3),
 163 .BR pthread_create (3),
 164 .BR pthreads (7)