summaryrefslogtreecommitdiff
path: root/lib/libpthread/pthread_attr_getstack.3
diff options
context:
space:
mode:
authorjruoho <jruoho@NetBSD.org>2010-07-07 11:04:52 +0000
committerjruoho <jruoho@NetBSD.org>2010-07-07 11:04:52 +0000
commit2bf45345dbb001c5cb1e808a007ad08d54dfff58 (patch)
tree61bf616b33fec156daba1d1667382617cdf3afc0 /lib/libpthread/pthread_attr_getstack.3
parent5544227ec791b8fc43da4fd09dba4910e9dc5c0a (diff)
Move the thread stack attribute functions to a separate page. In addition,
document pthread_attr_getstack() and pthread_attr_setstack(). Try to also document these a little better (in particular, note some items in the long list of caveats and questions related to application-controlled thread stack).
Diffstat (limited to 'lib/libpthread/pthread_attr_getstack.3')
-rw-r--r--lib/libpthread/pthread_attr_getstack.3177
1 files changed, 177 insertions, 0 deletions
diff --git a/lib/libpthread/pthread_attr_getstack.3 b/lib/libpthread/pthread_attr_getstack.3
new file mode 100644
index 00000000000..e76a89db29a
--- /dev/null
+++ b/lib/libpthread/pthread_attr_getstack.3
@@ -0,0 +1,177 @@
+.\" $NetBSD: pthread_attr_getstack.3,v 1.1 2010/07/07 11:04:54 jruoho Exp $
+.\"
+.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@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 7, 2010
+.Dt PTHREAD_ATTR_GETSTACK 3
+.Os
+.Sh NAME
+.Nm pthread_attr_getstack
+.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
+are 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.
+.Sh 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
+.Tn 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.
+.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.
+This implies that the application may need to also allocate a suitable
+guard area that is protected from reading and writing.
+.It
+Moreoever, 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
+.Sh STANDARDS
+The
+.Fn pthread_attr_getstack
+and
+.Fn pthread_attr_setstack
+functions as well as
+.Fn pthread_attr_getstacksize
+and
+.Fn pthread_attr_setstacksize
+conform to
+.St -p1003.1-2008 .
+The
+.Fn pthread_attr_getstackaddr
+and
+.Fn pthread_attr_setstackaddr
+conform to
+.St -p1003.1-2004 ,
+where these were marked as obsolescent due concerns about portability.
+The 2008 revision removed these two functions from the specification.