1.\" $NetBSD: pthread_attr_getstack.3,v 1.5 2010/07/09 17:15:59 jruoho 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 9, 2010 29.Dt PTHREAD_ATTR_GETSTACK 3 30.Os 31.Sh NAME 32.Nm pthread_attr_getstack 33.Nd get and set thread stack attributes 34.Sh LIBRARY 35.Lb libpthread 36.Sh SYNOPSIS 37.In pthread.h 38.Ft int 39.Fn pthread_attr_getstack \ 40"const pthread_attr_t * restrict attr" \ 41"void ** restrict stackaddr, size_t * restrict stacksize" 42.Ft int 43.Fn pthread_attr_setstack \ 44"pthread_attr_t * restrict attr" "void *stackaddr, size_t stacksize" 45.Ft int 46.Fn pthread_attr_getstacksize \ 47"const pthread_attr_t * restrict attr" "size_t * restrict stacksize" 48.Ft int 49.Fn pthread_attr_setstacksize \ 50"pthread_attr_t *attr" "size_t stacksize" 51.Ft int 52.Fn pthread_attr_getstackaddr \ 53"const pthread_attr_t * restrict attr" "void ** restrict stackaddr" 54.Ft int 55.Fn pthread_attr_setstackaddr \ 56"pthread_attr_t *attr" "void *stackaddr" 57.Sh DESCRIPTION 58The 59.Fn pthread_attr_getstack 60and 61.Fn pthread_attr_setstack 62functions get and set, respectively, the thread stack attributes 63.Fa stackaddr 64and 65.Fa stacksize 66in the 67.Fa attr 68object. 69The remaining four functions behave similarly, 70but instead of getting or setting both 71.Fa stackaddr 72and 73.Fa stacksize , 74these get and set the values individually. 75.Pp 76The 77.Fa stacksize 78parameter is defined to be the minimum stack size (in bytes) 79allocated for the thread's stack during the creation of the thread. 80The 81.Fa stackaddr 82attribute specifies the location of storage to be used for the thread's stack. 83All pages within the stack described by 84.Fa stackaddr 85and 86.Fa stacksize 87should be both readable and writable by the thread. 88.Pp 89The behavior is undefined in all functions if the 90.Fa attr 91parameter does not refer to an attribute object initialized by using 92.Xr pthread_attr_init 3 93prior to the call. 94In addition, undefined behavior may follow if the 95.Fn pthread_attr_getstack 96function is called before the 97.Fa stackaddr 98attribute has been set. 99.Ss Rationale 100The rationale behind these functions is to address cases where an application 101may be used in an environment where the stack of a thread must be placed to 102some particular region of memory. 103For the majority of applications, this is seldom necessary, 104and the use of these functions should be generally avoided. 105At least few potential caveats can be mentioned. 106.Bl -bullet -offset 2n 107.It 108There is a certain degree of ambiguity in the 109.Tn POSIX 110standard with respect to thread stack. 111.It 112The exact behavior of the functions may vary 113both across machines and operating systems. 114In particular, the address specified by 115.Fa stackaddr 116should be suitably aligned. 117The system page size, as specified by 118.Xr sysconf 3 , 119and the use of 120.Xr posix_memalign 3 121may guarantee some degree of portability. 122Also 123.Xr mmap 2 124provides means for alignment. 125.It 126If the application modifies the stack address, it claims also 127the responsibility of allocating the stack area and guarding it against 128possible stack overflow. 129No default guard area will be allocated (see 130.Xr pthread_attr_getguardsize 3 ) . 131It may be necessary to manually use 132.Xr mprotect 2 133in order to define a guard area at the end of the allocated stack. 134.It 135Moreover, if 136.Fa attr 137is used to create multiple threads, the stack address must be changed 138by the application between successive calls to 139.Xr pthread_create 3 . 140.El 141.Sh RETURN VALUES 142If successful, these functions return 0. 143Otherwise, an error number is returned to indicate the error. 144.Sh ERRORS 145No errors are defined for the three functions that obtain the stack values. 146The three functions that set the stack values may fail if: 147.Bl -tag -width Er 148.It Bq Er ENOMEM 149There was insufficient memory to complete the operation. 150.El 151.Pp 152The 153.Fn pthread_attr_setstacksize 154function may additionally fail if: 155.Bl -tag -width Er 156.It Bq Er EINVAL 157The specified 158.Fa stacksize 159is less than 160.Dv PTHREAD_STACK_MIN 161or exceeds some system-imposed limit. 162.El 163.Sh SEE ALSO 164.Xr pthread_attr 3 , 165.Xr pthread_attr_setguardsize 3 166.Sh STANDARDS 167All described functions conform to 168.St -p1003.1-2001 . 169Note that 170.Fn pthread_attr_getstackaddr 171and 172.Fn pthread_attr_setstackaddr 173were however removed from the specification in the 174.St -p1003.1-2008 175revision. 176