From 253e67c8b3a72b3a4757fdbc5845297628db0a4a Mon Sep 17 00:00:00 2001 From: Jacob McDonnell Date: Sat, 25 Apr 2026 19:55:15 -0400 Subject: docs: Added All NetBSD Manuals --- static/netbsd/man3/pthread_attr_getstack.3 | 203 +++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 static/netbsd/man3/pthread_attr_getstack.3 (limited to 'static/netbsd/man3/pthread_attr_getstack.3') diff --git a/static/netbsd/man3/pthread_attr_getstack.3 b/static/netbsd/man3/pthread_attr_getstack.3 new file mode 100644 index 00000000..ba003d72 --- /dev/null +++ b/static/netbsd/man3/pthread_attr_getstack.3 @@ -0,0 +1,203 @@ +.\" $NetBSD: pthread_attr_getstack.3,v 1.9 2023/12/07 16:55:01 riastradh Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen +.\" 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 +.In 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. +.Pp +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. +.Pp +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. +.Bl -bullet -offset 2n +.It +There is a certain degree of ambiguity in the POSIX +standard with respect to thread stack. +.It +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. +.It +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. +.It +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: +.Bl -tag -width Er +.It Bq Er ENOMEM +There was insufficient memory to complete the operation. +.El +.Pp +The +.Fn pthread_attr_setstacksize +function may additionally fail if: +.Bl -tag -width Er +.It 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 +.Po +see +.Lk https://gnats.NetBSD.org/57721 "PR lib/57721" +.Pc . +.Pp +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. +.Pp +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);" -- cgit v1.2.3