.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PTHREAD_ATTR_GETSTACK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" pthread_attr_getstack 
.SH NAME
pthread_attr_getstack, pthread_attr_setstack \- get and set stack attributes
.SH SYNOPSIS
.LP
\fB#include <pthread.h>
.br
.sp
\fBint pthread_attr_getstack(const pthread_attr_t *restrict\fP \fIattr\fP\fB,
.br
\ \ \ \ \ \  void **restrict\fP \fIstackaddr\fP\fB, size_t *restrict\fP
\fIstacksize\fP\fB);
.br
int pthread_attr_setstack(pthread_attr_t *\fP\fIattr\fP\fB, void *\fP\fIstackaddr\fP\fB,
.br
\ \ \ \ \ \  size_t\fP \fIstacksize\fP\fB); \fP
.sp
\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIpthread_attr_getstack\fP() and \fIpthread_attr_setstack\fP()
functions, respectively, shall get and set the thread
creation stack attributes \fIstackaddr\fP and \fIstacksize\fP in the
\fIattr\fP object.
.LP
The stack attributes specify the area of storage to be used for the
created thread's stack. The base (lowest addressable byte)
of the storage shall be \fIstackaddr\fP, and the size of the storage
shall be \fIstacksize\fP bytes. The \fIstacksize\fP shall
be at least {PTHREAD_STACK_MIN}. The \fIstackaddr\fP shall be aligned
appropriately to be used as a stack; for example,
\fIpthread_attr_setstack\fP() may fail with [EINVAL] if ( \fIstackaddr\fP
& 0x7) is not 0. All pages within the stack
described by \fIstackaddr\fP and \fIstacksize\fP shall be both readable
and writable by the thread.
.SH RETURN VALUE
.LP
Upon successful completion, these functions shall return a value of
0; otherwise, an error number shall be returned to indicate
the error.
.LP
The \fIpthread_attr_getstack\fP() function shall store the stack attribute
values in \fIstackaddr\fP and \fIstacksize\fP if
successful.
.SH ERRORS
.LP
The \fIpthread_attr_setstack\fP() function shall fail if:
.TP 7
.B EINVAL
The value of \fIstacksize\fP is less than {PTHREAD_STACK_MIN} or exceeds
an implementation-defined limit.
.sp
.LP
The \fIpthread_attr_setstack\fP() function may fail if:
.TP 7
.B EINVAL
The value of \fIstackaddr\fP does not have proper alignment to be
used as a stack, or if ( \fIstackaddr\fP +
\fIstacksize\fP) lacks proper alignment.
.TP 7
.B EACCES
The stack page(s) described by \fIstackaddr\fP and \fIstacksize\fP
are not both readable and writable by the thread.
.sp
.LP
These functions shall not return an error code of [EINTR].
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
These functions are appropriate for use by applications in an environment
where the stack for a thread must be placed in some
particular region of memory.
.LP
While it might seem that an application could detect stack overflow
by providing a protected page outside the specified stack
region, this cannot be done portably. Implementations are free to
place the thread's initial stack pointer anywhere within the
specified region to accommodate the machine's stack pointer behavior
and allocation requirements. Furthermore, on some
architectures, such as the IA-64, "overflow" might mean that two separate
stack pointers allocated within the region will overlap
somewhere in the middle of the region.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIpthread_attr_init\fP() , \fIpthread_attr_setdetachstate\fP() ,
\fIpthread_attr_setstacksize\fP() , \fIpthread_create\fP()
, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<limits.h>\fP,
\fI<pthread.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .