Debian Codegraph @

upstream/debian-unstable/man3/pthread_attr_setguardsize.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_attr_setguardsize 3 2025-05-17 "Linux man-pages 6.18"
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 .P
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 .P
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 .P
41 If
42 .I guardsize
43 is 0, then new threads created with
44 .I attr
45 will not have a guard area.
46 .P
47 The default guard size is the same as the system page size.
48 .P
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 .P
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 ATTRIBUTES
86 For an explanation of the terms used in this section, see
87 .BR attributes (7).
88 .TS
89 allbox;
90 lbx lb lb
91 l l l.
92 Interface Attribute Value
93 T{
94 .na
95 .nh
96 .BR pthread_attr_setguardsize (),
97 .BR pthread_attr_getguardsize ()
98 T} Thread safety MT-Safe
99 .TE
100 .SH STANDARDS
101 POSIX.1-2008.
102 .SH HISTORY
103 glibc 2.1.
104 POSIX.1-2001.
105 .SH NOTES
106 A guard area consists of virtual memory pages that are protected
107 to prevent read and write access.
108 If a thread overflows its stack into the guard area,
109 then, on most hard architectures, it receives a
110 .B SIGSEGV
111 signal, thus notifying it of the overflow.
112 Guard areas start on page boundaries,
113 and the guard size is internally rounded up to
114 the system page size when creating a thread.
115 (Nevertheless,
116 .BR pthread_attr_getguardsize ()
117 returns the guard size that was set by
118 .BR pthread_attr_setguardsize ().)
119 .P
120 Setting a guard size of 0 may be useful to save memory
121 in an application that creates many threads
122 and knows that stack overflow can never occur.
123 .P
124 Choosing a guard size larger than the default size
125 may be necessary for detecting stack overflows
126 if a thread allocates large data structures on the stack.
127 .SH BUGS
128 As at glibc 2.8, the NPTL threading implementation includes
129 the guard area within the stack size allocation,
130 rather than allocating extra space at the end of the stack,
131 as POSIX.1 requires.
132 (This can result in an
133 .B EINVAL
134 error from
135 .BR pthread_create (3)
136 if the guard size value is too large,
137 leaving no space for the actual stack.)
138 .P
139 The obsolete LinuxThreads implementation did the right thing,
140 allocating extra space at the end of the stack for the guard area.
141 .\" glibc includes the guardsize within the allocated stack size,
142 .\" which looks pretty clearly to be in violation of POSIX.
143 .\"
144 .\" Filed bug, 22 Oct 2008:
145 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6973
146 .\"
147 .\" Older reports:
148 .\" https//bugzilla.redhat.com/show_bug.cgi?id=435337
149 .\" Reportedly, LinuxThreads did the right thing, allocating
150 .\" extra space at the end of the stack:
151 .\" http://sourceware.org/ml/libc-alpha/2008-05/msg00086.html
152 .SH EXAMPLES
153 See
154 .BR pthread_getattr_np (3).
155 .SH SEE ALSO
156 .BR mmap (2),
157 .BR mprotect (2),
158 .BR pthread_attr_init (3),
159 .BR pthread_attr_setstack (3),
160 .BR pthread_attr_setstacksize (3),
161 .BR pthread_create (3),
162 .BR pthreads (7)