1.\" $NetBSD: pthread_attr_getguardsize.3,v 1.2 2010/07/08 18:24:34 wiz 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 70.Dv _SC_PAGESIZE , 71the system page size. 72.Pp 73The rationale behind 74.Fa guardsize 75is two-fold: 76.Bl -enum -offset 2n 77.It 78On the one hand, it provides protection against overflow of the stack pointer. 79If there is a guard area and a thread overflows its 80stack pointer into this extra memory area, it should receive a 81.Dv SIGSEGV 82signal or experience other comparable fatal error condition. 83Note that if a thread allocates large data structures on stack, 84it may be necessary to raise the default 85.Fa guardsize 86in order to detect stack overflows. 87.It 88On the other hand, the overflow protection may waste system resources 89if an application that creates a large number of threads knows that it 90will never overflow the stack. 91In this case it is possible to set 92.Fa guardsize 93to 0. 94.El 95.Pp 96If 97.Xr pthread_attr_setstack 3 98or 99.Xr pthread_attr_setstackaddr 3 100is used to set the stack address attribute in 101.Fa attr , 102the guard size attribute is ignored and no guard area will be allocated; 103it is the responsibility of the application to handle the overflow conditions. 104.Sh RETURN VALUES 105If successful, both functions return 0. 106Otherwise, an error number is returned to indicate the error. 107.Sh ERRORS 108No errors are defined for 109.Fn pthread_attr_getguardsize . 110.Pp 111The 112.Fn pthread_attr_setguardsize 113may fail if: 114.Bl -tag -width Er 115.It Bq Er ENOMEM 116There was insufficient memory. 117.El 118.Sh SEE ALSO 119.Xr pthread_attr 3 , 120.Xr pthread_attr_setstack 3 , 121.Xr sysconf 3 122.Sh STANDARDS 123Both functions conform to 124.St -p1003.1-2008 . 125