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).
This commit is contained in:
jruoho
parent
5544227ec7
commit
2bf45345db
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 @@ MAN+= affinity.3 pthread.3 \
|
|||
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+= affinity.3 pthread_getaffinity_np.3
|
|||
|
||||
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.3 pthread_attr_getschedpolicy.3
|
|||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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 @@ The value specified by
|
|||
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 @@ Invalid or unsupported value for
|
|||
.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 ,
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue