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