1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
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.
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.
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
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH PTHREAD_ATTR_SETGUARDSIZE 3 2017-09-15 "Linux" "Linux Programmer's Manual"
28 pthread_attr_setguardsize, pthread_attr_getguardsize \- set/get guard size
29 attribute in thread attributes object
32 .B #include <pthread.h>
34 .BI "int pthread_attr_setguardsize(pthread_attr_t *" attr \
35 ", size_t " guardsize );
36 .BI "int pthread_attr_getguardsize(const pthread_attr_t *" attr \
37 ", size_t *" guardsize );
39 Compile and link with \fI\-pthread\fP.
43 .BR pthread_attr_setguardsize ()
44 function sets the guard size attribute of the
45 thread attributes object referred to by
47 to the value specified in
53 then for each new thread created using
55 the system allocates an additional region of at least
57 bytes at the end of the thread's stack to act as the guard area
58 for the stack (but see BUGS).
62 is 0, then new threads created with
64 will not have a guard area.
66 The default guard size is the same as the system page size.
68 If the stack address attribute has been set in
71 .BR pthread_attr_setstack (3)
73 .BR pthread_attr_setstackaddr (3)),
74 meaning that the caller is allocating the thread's stack,
75 then the guard size attribute is ignored
76 (i.e., no guard area is created by the system):
77 it is the application's responsibility to handle stack overflow
80 to manually define a guard area at the end of the stack
81 that it has allocated).
84 .BR pthread_attr_getguardsize ()
85 function returns the guard size attribute of the
86 thread attributes object referred to by
88 in the buffer pointed to by
91 On success, these functions return 0;
92 on error, they return a nonzero error number.
101 On Linux these functions always succeed
102 (but portable and future-proof applications should nevertheless
103 handle a possible error return).
105 These functions are provided by glibc since version 2.1.
107 For an explanation of the terms used in this section, see
113 Interface Attribute Value
115 .BR pthread_attr_setguardsize (),
116 .BR pthread_attr_getguardsize ()
117 T} Thread safety MT-Safe
120 POSIX.1-2001, POSIX.1-2008.
122 A guard area consists of virtual memory pages that are protected
123 to prevent read and write access.
124 If a thread overflows its stack into the guard area,
125 then, on most hard architectures, it receives a
127 signal, thus notifying it of the overflow.
128 Guard areas start on page boundaries,
129 and the guard size is internally rounded up to
130 the system page size when creating a thread.
132 .BR pthread_attr_getguardsize ()
133 returns the guard size that was set by
134 .BR pthread_attr_setguardsize ().)
136 Setting a guard size of 0 may be useful to save memory
137 in an application that creates many threads
138 and knows that stack overflow can never occur.
140 Choosing a guard size larger than the default size
141 may be necessary for detecting stack overflows
142 if a thread allocates large data structures on the stack.
144 As at glibc 2.8, the NPTL threading implementation includes
145 the guard area within the stack size allocation,
146 rather than allocating extra space at the end of the stack,
148 (This can result in an
151 .BR pthread_create (3)
152 if the guard size value is too large,
153 leaving no space for the actual stack.)
155 The obsolete LinuxThreads implementation did the right thing,
156 allocating extra space at the end of the stack for the guard area.
157 .\" glibc includes the guardsize within the allocated stack size,
158 .\" which looks pretty clearly to be in violation of POSIX.
160 .\" Filed bug, 22 Oct 2008:
161 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6973
164 .\" https//bugzilla.redhat.com/show_bug.cgi?id=435337
165 .\" Reportedly, LinuxThreads did the right thing, allocating
166 .\" extra space at the end of the stack:
167 .\" http://sourceware.org/ml/libc-alpha/2008-05/msg00086.html
170 .BR pthread_getattr_np (3).
174 .BR pthread_attr_init (3),
175 .BR pthread_attr_setstack (3),
176 .BR pthread_attr_setstacksize (3),
177 .BR pthread_create (3),