Module Name: src
Committed By: jruoho
Date: Wed Jul 7 11:04:54 UTC 2010
Modified Files:
src/distrib/sets/lists/comp: mi
src/lib/libpthread: Makefile pthread_attr.3
Added Files:
src/lib/libpthread: pthread_attr_getstack.3
Log Message:
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).
To generate a diff of this commit:
cvs rdiff -u -r1.1479 -r1.1480 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.60 -r1.61 src/lib/libpthread/Makefile
cvs rdiff -u -r1.13 -r1.14 src/lib/libpthread/pthread_attr.3
cvs rdiff -u -r0 -r1.1 src/lib/libpthread/pthread_attr_getstack.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1479 src/distrib/sets/lists/comp/mi:1.1480
--- src/distrib/sets/lists/comp/mi:1.1479 Tue Jul 6 21:36:34 2010
+++ src/distrib/sets/lists/comp/mi Wed Jul 7 11:04:52 2010
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1479 2010/07/06 21:36:34 jruoho Exp $
+# $NetBSD: mi,v 1.1480 2010/07/07 11:04:52 jruoho Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -7571,6 +7571,7 @@
./usr/share/man/cat3/pthread_attr_getschedparam.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_attr_getschedpolicy.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_attr_getscope.0 comp-c-catman .cat
+./usr/share/man/cat3/pthread_attr_getstack.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_attr_getstackaddr.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_attr_getstacksize.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_attr_init.0 comp-c-catman .cat
@@ -7582,6 +7583,7 @@
./usr/share/man/cat3/pthread_attr_setschedparam.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_attr_setschedpolicy.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_attr_setscope.0 comp-c-catman .cat
+./usr/share/man/cat3/pthread_attr_setstack.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_attr_setstackaddr.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_attr_setstacksize.0 comp-c-catman .cat
./usr/share/man/cat3/pthread_barierattr_destroy.0 comp-obsolete obsolete
@@ -13409,6 +13411,7 @@
./usr/share/man/html3/pthread_attr_getschedparam.html comp-c-htmlman html
./usr/share/man/html3/pthread_attr_getschedpolicy.html comp-c-htmlman html
./usr/share/man/html3/pthread_attr_getscope.html comp-c-htmlman html
+./usr/share/man/html3/pthread_attr_getstack.html comp-c-htmlman html
./usr/share/man/html3/pthread_attr_getstackaddr.html comp-c-htmlman html
./usr/share/man/html3/pthread_attr_getstacksize.html comp-c-htmlman html
./usr/share/man/html3/pthread_attr_init.html comp-c-htmlman html
@@ -13420,6 +13423,7 @@
./usr/share/man/html3/pthread_attr_setschedparam.html comp-c-htmlman html
./usr/share/man/html3/pthread_attr_setschedpolicy.html comp-c-htmlman html
./usr/share/man/html3/pthread_attr_setscope.html comp-c-htmlman html
+./usr/share/man/html3/pthread_attr_setstack.html comp-c-htmlman html
./usr/share/man/html3/pthread_attr_setstackaddr.html comp-c-htmlman html
./usr/share/man/html3/pthread_attr_setstacksize.html comp-c-htmlman html
./usr/share/man/html3/pthread_barrier_destroy.html comp-c-htmlman html
@@ -19241,6 +19245,7 @@
./usr/share/man/man3/pthread_attr_getschedparam.3 comp-c-man .man
./usr/share/man/man3/pthread_attr_getschedpolicy.3 comp-c-man .man
./usr/share/man/man3/pthread_attr_getscope.3 comp-c-man .man
+./usr/share/man/man3/pthread_attr_getstack.3 comp-c-man .man
./usr/share/man/man3/pthread_attr_getstackaddr.3 comp-c-man .man
./usr/share/man/man3/pthread_attr_getstacksize.3 comp-c-man .man
./usr/share/man/man3/pthread_attr_init.3 comp-c-man .man
@@ -19252,6 +19257,7 @@
./usr/share/man/man3/pthread_attr_setschedparam.3 comp-c-man .man
./usr/share/man/man3/pthread_attr_setschedpolicy.3 comp-c-man .man
./usr/share/man/man3/pthread_attr_setscope.3 comp-c-man .man
+./usr/share/man/man3/pthread_attr_setstack.3 comp-c-man .man
./usr/share/man/man3/pthread_attr_setstackaddr.3 comp-c-man .man
./usr/share/man/man3/pthread_attr_setstacksize.3 comp-c-man .man
./usr/share/man/man3/pthread_barierattr_destroy.3 comp-obsolete obsolete
Index: src/lib/libpthread/Makefile
diff -u src/lib/libpthread/Makefile:1.60 src/lib/libpthread/Makefile:1.61
--- src/lib/libpthread/Makefile:1.60 Wed Jul 7 08:57:36 2010
+++ src/lib/libpthread/Makefile Wed Jul 7 11:04:54 2010
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.60 2010/07/07 08:57:36 jruoho Exp $
+# $NetBSD: Makefile,v 1.61 2010/07/07 11:04:54 jruoho Exp $
#
WARNS= 4
@@ -93,6 +93,7 @@
pthread_attr_getdetachstate.3 \
pthread_attr_getname_np.3 \
pthread_attr_getscope.3 \
+ pthread_attr_getstack.3 \
pthread_attr_setcreatesuspend_np.3 \
pthread_attr_setname_np.3 \
pthread_barrier_destroy.3 pthread_barrier_init.3 \
@@ -121,12 +122,8 @@
MLINKS+= pthread_attr.3 pthread_attr_init.3
MLINKS+= pthread_attr.3 pthread_attr_destroy.3
-MLINKS+= pthread_attr.3 pthread_attr_setstacksize.3
-MLINKS+= pthread_attr.3 pthread_attr_getstacksize.3
MLINKS+= pthread_attr.3 pthread_attr_setguardsize.3
MLINKS+= pthread_attr.3 pthread_attr_getguardsize.3
-MLINKS+= pthread_attr.3 pthread_attr_setstackaddr.3
-MLINKS+= pthread_attr.3 pthread_attr_getstackaddr.3
MLINKS+= pthread_attr.3 pthread_attr_setinheritsched.3
MLINKS+= pthread_attr.3 pthread_attr_getinheritsched.3
MLINKS+= pthread_attr.3 pthread_attr_setschedparam.3
@@ -136,6 +133,11 @@
MLINKS+= pthread_attr_getdetachstate.3 pthread_attr_setdetachstate.3
MLINKS+= pthread_attr_getscope.3 pthread_attr_setscope.3
+MLINKS+= pthread_attr_getstack.3 pthread_attr_setstack.3 \
+ pthread_attr_getstack.3 pthread_attr_getstacksize.3 \
+ pthread_attr_getstack.3 pthread_attr_setstacksize.3 \
+ pthread_attr_getstack.3 pthread_attr_getstackaddr.3 \
+ pthread_attr_getstack.3 pthread_attr_setstackaddr.3
MLINKS+= pthread_barrierattr.3 pthread_barrierattr_init.3
MLINKS+= pthread_barrierattr.3 pthread_barrierattr_destroy.3
Index: src/lib/libpthread/pthread_attr.3
diff -u src/lib/libpthread/pthread_attr.3:1.13 src/lib/libpthread/pthread_attr.3:1.14
--- src/lib/libpthread/pthread_attr.3:1.13 Wed Jul 7 08:57:36 2010
+++ src/lib/libpthread/pthread_attr.3 Wed Jul 7 11:04:54 2010
@@ -1,4 +1,4 @@
-.\" $NetBSD: pthread_attr.3,v 1.13 2010/07/07 08:57:36 jruoho Exp $
+.\" $NetBSD: pthread_attr.3,v 1.14 2010/07/07 11:04:54 jruoho Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -59,12 +59,8 @@
.Sh NAME
.Nm pthread_attr_init ,
.Nm pthread_attr_destroy ,
-.Nm pthread_attr_setstacksize ,
-.Nm pthread_attr_getstacksize ,
.Nm pthread_attr_setguardsize ,
.Nm pthread_attr_getguardsize ,
-.Nm pthread_attr_setstackaddr ,
-.Nm pthread_attr_getstackaddr ,
.Nm pthread_attr_setinheritsched ,
.Nm pthread_attr_getinheritsched ,
.Nm pthread_attr_setschedparam ,
@@ -81,18 +77,10 @@
.Ft int
.Fn pthread_attr_destroy "pthread_attr_t *attr"
.Ft int
-.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
-.Ft int
-.Fn pthread_attr_getstacksize "const pthread_attr_t * restrict attr" "size_t * restrict stacksize"
-.Ft int
.Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize"
.Ft int
.Fn pthread_attr_getguardsize "const pthread_attr_t * restrict attr" "size_t * restrict guardsize"
.Ft int
-.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
-.Ft int
-.Fn pthread_attr_getstackaddr "const pthread_attr_t * restrict attr" "void ** restrict stackaddr"
-.Ft int
.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
.Ft int
.Fn pthread_attr_getinheritsched "const pthread_attr_t * restrict attr" "int * restrict inheritsched"
@@ -150,16 +138,7 @@
is invalid.
.El
.Pp
-.Fn pthread_attr_setstacksize
-may fail if:
-.Bl -tag -width Er
-.It Bq Er EINVAL
-.Fa stacksize
-is less than
-.Dv PTHREAD_STACK_MIN .
-.El
-.Pp
-Fn pthread_attr_setinheritsched
+.Fn pthread_attr_setinheritsched
may fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
@@ -196,10 +175,6 @@
.Sh STANDARDS
.Fn pthread_attr_init ,
.Fn pthread_attr_destroy ,
-.Fn pthread_attr_setstacksize ,
-.Fn pthread_attr_getstacksize ,
-.Fn pthread_attr_setstackaddr ,
-.Fn pthread_attr_getstackaddr ,
.Fn pthread_attr_setinheritsched ,
.Fn pthread_attr_getinheritsched ,
.Fn pthread_attr_setschedparam ,
Added files:
Index: src/lib/libpthread/pthread_attr_getstack.3
diff -u /dev/null src/lib/libpthread/pthread_attr_getstack.3:1.1
--- /dev/null Wed Jul 7 11:04:54 2010
+++ src/lib/libpthread/pthread_attr_getstack.3 Wed Jul 7 11:04:54 2010
@@ -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 <jruoho...@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.
