1.\" $NetBSD: pthread_attr_getguardsize.3,v 1.6 2023/12/07 16:55:01 riastradh Exp $ 2.\" 3.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 17.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 18.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26.\" POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd July 2, 2017 29.Dt PTHREAD_ATTR_GETGUARDSIZE 3 30.Os 31.Sh NAME 32.Nm pthread_attr_getguardsize , 33.Nm pthread_attr_setguardsize 34.Nd get and set thread guard size 35.Sh LIBRARY 36.Lb libpthread 37.Sh SYNOPSIS 38.In pthread.h 39.Ft int 40.Fn pthread_attr_getguardsize \ 41"const pthread_attr_t * restrict attr" "size_t * restrict guardsize" 42.Ft int 43.Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize" 44.Sh DESCRIPTION 45The 46.Fn pthread_attr_getguardsize 47and 48.Fn pthread_attr_setguardsize 49functions get and set 50.Fa guardsize 51in the 52.Fa attr 53object. 54If 55.Fa guardsize 56is larger than 0, the system reserves 57an additional region of guarded memory of at least 58.Fa guardsize 59bytes at the end of the thread's stack for each new thread created by using 60.Fa attr . 61.Pp 62The guarded area is understood to be pages of memory 63that are protected from read and write access. 64While the guarded area should be rounded by the system page size, 65the actual default size is implementation-defined. 66In 67.Nx 68the default 69.Fa guardsize 70is given by the 71.Pa vm.thread_guard_size 72.Xr sysctl 7 . 73.Pp 74The rationale behind 75.Fa guardsize 76is two-fold: 77.Bl -enum -offset 2n 78.It 79On the one hand, it provides protection against overflow of the stack pointer. 80If there is a guard area and a thread overflows its 81stack pointer into this extra memory area, it should receive a 82.Dv SIGSEGV 83signal or experience other comparable fatal error condition. 84Note that if a thread allocates large data structures on stack, 85it may be necessary to raise the default 86.Fa guardsize 87in order to detect stack overflows. 88.It 89On the other hand, the overflow protection may waste system resources 90if an application that creates a large number of threads knows that it 91will never overflow the stack. 92In this case it is possible to set 93.Fa guardsize 94to 0. 95.El 96.Pp 97If 98.Xr pthread_attr_setstack 3 99or 100.Xr pthread_attr_setstackaddr 3 101is used to set the stack address attribute in 102.Fa attr , 103the guard size attribute is ignored and no guard area will be allocated; 104it is the responsibility of the application to handle the overflow conditions. 105.Sh RETURN VALUES 106If successful, both functions return 0. 107Otherwise, an error number is returned to indicate the error. 108.Sh ERRORS 109No errors are defined for 110.Fn pthread_attr_getguardsize . 111.Pp 112The 113.Fn pthread_attr_setguardsize 114may fail if: 115.Bl -tag -width Er 116.It Bq Er ENOMEM 117There was insufficient memory. 118.El 119.Sh SEE ALSO 120.Xr pthread_attr 3 , 121.Xr pthread_attr_setstack 3 , 122.Xr sysconf 3 123.Sh STANDARDS 124Both functions conform to 125.St -p1003.1-2008 . 126.Sh BUGS 127Older versions of 128.Nx , 129prior to 10.0, 9.4, and 8.3, incorrectly adjust the stack address by 130the guard size in threads configured with 131.Xr pthread_attr_setstack 3 , 132instead of ignoring the guard size in that case as 133.Tn POSIX 134prescribes 135.Po 136see 137.Lk https://gnats.NetBSD.org/57721 "PR lib/57721" 138.Pc . 139.Pp 140Even if you didn't set a nonzero guard size with 141.Fn pthread_attr_setguardsize , 142the system will choose a nonzero default guard size. 143.Pp 144To work around this in applications that run on older and newer 145versions of 146.Nx , 147as well as on other operating systems, you can safely set the guard 148size to zero: 149.Dl "pthread_attr_setguardsize(&attr, 0);" 150