Copyright (c) 2010 Jukka Ruohonen <jruohonen (at] iki.fi>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd July 9, 2010 .Dt PTHREAD_ATTR_GETSTACK 3 .Os .Sh NAME .Nm pthread_attr_getstack , .Nm pthread_attr_setstack , .Nm pthread_attr_getstacksize , .Nm pthread_attr_setstacksize , .Nm pthread_attr_getstackaddr , .Nm pthread_attr_setstackaddr .Nd get and set thread stack attributes .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS n pthread.h .Ft int .Fn pthread_attr_getstack \ "const pthread_attr_t * restrict attr" \ "void ** restrict stackaddr" "size_t * restrict stacksize" .Ft int .Fn pthread_attr_setstack \ "pthread_attr_t * restrict attr" "void *stackaddr" "size_t stacksize" .Ft int .Fn pthread_attr_getstacksize \ "const pthread_attr_t * restrict attr" "size_t * restrict stacksize" .Ft int .Fn pthread_attr_setstacksize \ "pthread_attr_t *attr" "size_t stacksize" .Ft int .Fn pthread_attr_getstackaddr \ "const pthread_attr_t * restrict attr" "void ** restrict stackaddr" .Ft int .Fn pthread_attr_setstackaddr \ "pthread_attr_t *attr" "void *stackaddr" .Sh DESCRIPTION The .Fn pthread_attr_getstack and .Fn pthread_attr_setstack functions get and set, respectively, the thread stack attributes .Fa stackaddr and .Fa stacksize in the .Fa attr object. The remaining four functions behave similarly, but instead of getting or setting both .Fa stackaddr and .Fa stacksize , these get and set the values individually.
p The .Fa stacksize parameter is defined to be the minimum stack size (in bytes) allocated for the thread's stack during the creation of the thread. The .Fa stackaddr attribute specifies the location of storage to be used for the thread's stack. All pages within the stack described by .Fa stackaddr and .Fa stacksize should be both readable and writable by the thread.
p The behavior is undefined in all functions if the .Fa attr parameter does not refer to an attribute object initialized by using .Xr pthread_attr_init 3 prior to the call. In addition, undefined behavior may follow if the .Fn pthread_attr_getstack function is called before the .Fa stackaddr attribute has been set. .Ss Rationale The rationale behind these functions is to address cases where an application may be used in an environment where the stack of a thread must be placed to some particular region of memory. For the majority of applications, this is seldom necessary, and the use of these functions should be generally avoided. At least few potential caveats can be mentioned. l -bullet -offset 2n t There is a certain degree of ambiguity in the POSIX standard with respect to thread stack. t The exact behavior of the functions may vary both across machines and operating systems. In particular, the address specified by .Fa stackaddr should be suitably aligned. The system page size, as specified by .Xr sysconf 3 , and the use of .Xr posix_memalign 3 may guarantee some degree of portability. Also .Xr mmap 2 provides means for alignment. t If the application modifies the stack address, it claims also the responsibility of allocating the stack area and guarding it against possible stack overflow. No default guard area will be allocated (see .Xr pthread_attr_getguardsize 3 ) . It may be necessary to manually use .Xr mprotect 2 in order to define a guard area at the end of the allocated stack. t Moreover, if .Fa attr is used to create multiple threads, the stack address must be changed by the application between successive calls to .Xr pthread_create 3 . .El .Sh RETURN VALUES If successful, these functions return 0. Otherwise, an error number is returned to indicate the error. .Sh ERRORS No errors are defined for the three functions that obtain the stack values. The three functions that set the stack values may fail if: l -tag -width Er t Bq Er ENOMEM There was insufficient memory to complete the operation. .El
p The .Fn pthread_attr_setstacksize function may additionally fail if: l -tag -width Er t Bq Er EINVAL The specified .Fa stacksize is less than .Dv PTHREAD_STACK_MIN or exceeds some system-imposed limit. .El .Sh SEE ALSO .Xr pthread_attr 3 , .Xr pthread_attr_setguardsize 3 .Sh STANDARDS All described functions conform to .St -p1003.1-2001 . Note that .Fn pthread_attr_getstackaddr and .Fn pthread_attr_setstackaddr were however removed from the specification in the .St -p1003.1-2008 revision. .Sh BUGS Older versions of .Nx , prior to 10.0, 9.4, and 8.3, incorrectly adjust the stack address by the guard size in threads configured with .Fn pthread_attr_setstack , instead of ignoring the guard size in that case as .Tn POSIX prescribes
o see .Lk https://gnats.NetBSD.org/57721 "PR lib/57721"
c .
p Even if you didn't set a nonzero guard size with .Xr pthread_attr_setguardsize 3 , the system will choose a nonzero default guard size.
p To work around this in applications that run on older and newer versions of .Nx , as well as on other operating systems, you can safely set the guard size to zero: .Dl "pthread_attr_setguardsize(&attr, 0);"
Indexes created Sat Sep 20 22:09:52 GMT 2025