]>
Commit | Line | Data |
---|---|---|
62fba73a MK |
1 | .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
62fba73a MK |
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. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
62fba73a | 25 | .\" |
4b8c67d9 | 26 | .TH PTHREAD_ATTR_SETGUARDSIZE 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
62fba73a MK |
27 | .SH NAME |
28 | pthread_attr_setguardsize, pthread_attr_getguardsize \- set/get guard size | |
29 | attribute in thread attributes object | |
30 | .SH SYNOPSIS | |
31 | .nf | |
32 | .B #include <pthread.h> | |
dbfe9c70 | 33 | .PP |
62fba73a MK |
34 | .BI "int pthread_attr_setguardsize(pthread_attr_t *" attr \ |
35 | ", size_t " guardsize ); | |
e59f5f58 | 36 | .BI "int pthread_attr_getguardsize(const pthread_attr_t *" attr \ |
62fba73a | 37 | ", size_t *" guardsize ); |
68e4db0a | 38 | .PP |
62fba73a | 39 | Compile and link with \fI\-pthread\fP. |
6030f2d8 | 40 | .fi |
62fba73a MK |
41 | .SH DESCRIPTION |
42 | The | |
43 | .BR pthread_attr_setguardsize () | |
44 | function sets the guard size attribute of the | |
45 | thread attributes object referred to by | |
46 | .I attr | |
47 | to the value specified in | |
48 | .IR guardsize . | |
847e0d88 | 49 | .PP |
62fba73a MK |
50 | If |
51 | .I guardsize | |
52 | is greater than 0, | |
53 | then for each new thread created using | |
54 | .I attr | |
55 | the system allocates an additional region of at least | |
56 | .I guardsize | |
57 | bytes at the end of the thread's stack to act as the guard area | |
58 | for the stack (but see BUGS). | |
847e0d88 | 59 | .PP |
62fba73a MK |
60 | If |
61 | .I guardsize | |
62 | is 0, then new threads created with | |
63 | .I attr | |
64 | will not have a guard area. | |
847e0d88 | 65 | .PP |
62fba73a | 66 | The default guard size is the same as the system page size. |
847e0d88 | 67 | .PP |
62fba73a MK |
68 | If the stack address attribute has been set in |
69 | .I attr | |
70 | (using | |
71 | .BR pthread_attr_setstack (3) | |
72 | or | |
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 | |
78 | (perhaps by using | |
79 | .BR mprotect (2) | |
80 | to manually define a guard area at the end of the stack | |
81 | that it has allocated). | |
847e0d88 | 82 | .PP |
62fba73a MK |
83 | The |
84 | .BR pthread_attr_getguardsize () | |
85 | function returns the guard size attribute of the | |
86 | thread attributes object referred to by | |
87 | .I attr | |
88 | in the buffer pointed to by | |
89 | .IR guardsize . | |
90 | .SH RETURN VALUE | |
91 | On success, these functions return 0; | |
c7094399 | 92 | on error, they return a nonzero error number. |
62fba73a | 93 | .SH ERRORS |
dfd0215a | 94 | POSIX.1 documents an |
62fba73a MK |
95 | .B EINVAL |
96 | error if | |
97 | .I attr | |
98 | or | |
99 | .I guardsize | |
c5571b61 | 100 | is invalid. |
62fba73a MK |
101 | On Linux these functions always succeed |
102 | (but portable and future-proof applications should nevertheless | |
103 | handle a possible error return). | |
104 | .SH VERSIONS | |
105 | These functions are provided by glibc since version 2.1. | |
738e78b2 | 106 | .SH ATTRIBUTES |
3dfd9ad5 PH |
107 | For an explanation of the terms used in this section, see |
108 | .BR attributes (7). | |
109 | .TS | |
110 | allbox; | |
111 | lbw28 lb lb | |
112 | l l l. | |
113 | Interface Attribute Value | |
114 | T{ | |
115 | .BR pthread_attr_setguardsize (), | |
738e78b2 | 116 | .BR pthread_attr_getguardsize () |
3dfd9ad5 PH |
117 | T} Thread safety MT-Safe |
118 | .TE | |
62fba73a | 119 | .SH CONFORMING TO |
dfd0215a | 120 | POSIX.1-2001, POSIX.1-2008. |
62fba73a MK |
121 | .SH NOTES |
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 | |
126 | .B SIGSEGV | |
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. | |
131 | (Nevertheless, | |
132 | .BR pthread_attr_getguardsize () | |
133 | returns the guard size that was set by | |
134 | .BR pthread_attr_setguardsize ().) | |
847e0d88 | 135 | .PP |
62fba73a MK |
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. | |
847e0d88 | 139 | .PP |
62fba73a MK |
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. | |
143 | .SH BUGS | |
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, | |
147 | as POSIX.1 requires. | |
148 | (This can result in an | |
149 | .B EINVAL | |
150 | error from | |
151 | .BR pthread_create (3) | |
152 | if the guard size value is too large, | |
153 | leaving no space for the actual stack.) | |
847e0d88 | 154 | .PP |
62fba73a MK |
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. | |
c5571b61 | 159 | .\" |
62fba73a MK |
160 | .\" Filed bug, 22 Oct 2008: |
161 | .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6973 | |
162 | .\" | |
163 | .\" Older reports: | |
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 | |
168 | .SH EXAMPLE | |
169 | See | |
170 | .BR pthread_getattr_np (3). | |
171 | .SH SEE ALSO | |
172 | .BR mmap (2), | |
173 | .BR mprotect (2), | |
174 | .BR pthread_attr_init (3), | |
62fba73a MK |
175 | .BR pthread_attr_setstack (3), |
176 | .BR pthread_attr_setstacksize (3), | |
3e5c319e | 177 | .BR pthread_create (3), |
62fba73a | 178 | .BR pthreads (7) |