1.\" $NetBSD: pthread_attr_getguardsize.3,v 1.3 2016/04/07 06:21:48 dholland 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 7, 2010 29.Dt PTHREAD_ATTR_GETGUARDSIZE 3 30.Os 31.Sh NAME 32.Nm pthread_attr_getguardsize 33.Nd get and set thread guard size 34.Sh LIBRARY 35.Lb libpthread 36.Sh SYNOPSIS 37.In pthread.h 38.Ft int 39.Fn pthread_attr_getguardsize \ 40"const pthread_attr_t * restrict attr" "size_t * restrict guardsize" 41.Ft int 42.Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize" 43.Sh DESCRIPTION 44The 45.Fn pthread_attr_getguardsize 46and 47.Fn pthread_attr_setguardsize 48functions get and set 49.Fa guardsize 50in the 51.Fa attr 52object. 53If 54.Fa guardsize 55is larger than 0, the system reserves 56an additional region of guarded memory of at least 57.Fa guardsize 58bytes at the end of the thread's stack for each new thread created by using 59.Fa attr . 60.Pp 61The guarded area is understood to be pages of memory 62that are protected from read and write access. 63While the guarded area should be rounded by the system page size, 64the actual default size is implementation-defined. 65In 66.Nx 67the default 68.Fa guardsize 69is the system page size. 70(This value is often 4096 bytes but varies on some ports; the 71precise value can be retrieved by using 72.Xr sysconf 3 73with 74.Dv _SC_PAGESIZE . ) 75.Pp 76The rationale behind 77.Fa guardsize 78is two-fold: 79.Bl -enum -offset 2n 80.It 81On the one hand, it provides protection against overflow of the stack pointer. 82If there is a guard area and a thread overflows its 83stack pointer into this extra memory area, it should receive a 84.Dv SIGSEGV 85signal or experience other comparable fatal error condition. 86Note that if a thread allocates large data structures on stack, 87it may be necessary to raise the default 88.Fa guardsize 89in order to detect stack overflows. 90.It 91On the other hand, the overflow protection may waste system resources 92if an application that creates a large number of threads knows that it 93will never overflow the stack. 94In this case it is possible to set 95.Fa guardsize 96to 0. 97.El 98.Pp 99If 100.Xr pthread_attr_setstack 3 101or 102.Xr pthread_attr_setstackaddr 3 103is used to set the stack address attribute in 104.Fa attr , 105the guard size attribute is ignored and no guard area will be allocated; 106it is the responsibility of the application to handle the overflow conditions. 107.Sh RETURN VALUES 108If successful, both functions return 0. 109Otherwise, an error number is returned to indicate the error. 110.Sh ERRORS 111No errors are defined for 112.Fn pthread_attr_getguardsize . 113.Pp 114The 115.Fn pthread_attr_setguardsize 116may fail if: 117.Bl -tag -width Er 118.It Bq Er ENOMEM 119There was insufficient memory. 120.El 121.Sh SEE ALSO 122.Xr pthread_attr 3 , 123.Xr pthread_attr_setstack 3 , 124.Xr sysconf 3 125.Sh STANDARDS 126Both functions conform to 127.St -p1003.1-2008 . 128