.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PTHREAD_ATTR_GETGUARDSIZE" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" pthread_attr_getguardsize 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
pthread_attr_getguardsize, pthread_attr_setguardsize \- get and set
the thread guardsize attribute
.SH SYNOPSIS
.LP
\fB#include <pthread.h>
.br
.sp
int pthread_attr_getguardsize(const pthread_attr_t *restrict\fP \fIattr\fP\fB,
.br
\ \ \ \ \ \  size_t *restrict\fP \fIguardsize\fP\fB);
.br
int pthread_attr_setguardsize(pthread_attr_t\fP \fI*attr\fP\fB,
.br
\ \ \ \ \ \  size_t\fP \fIguardsize\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIpthread_attr_getguardsize\fP() function shall get the \fIguardsize\fP
attribute in the \fIattr\fP object. This
attribute shall be returned in the \fIguardsize\fP parameter.
.LP
The \fIpthread_attr_setguardsize\fP() function shall set the \fIguardsize\fP
attribute in the \fIattr\fP object. The new
value of this attribute shall be obtained from the \fIguardsize\fP
parameter. If \fIguardsize\fP is zero, a guard area shall not
be provided for threads created with \fIattr\fP. If \fIguardsize\fP
is greater than zero, a guard area of at least size
\fIguardsize\fP bytes shall be provided for each thread created with
\fIattr\fP.
.LP
The \fIguardsize\fP attribute controls the size of the guard area
for the created thread's stack. The \fIguardsize\fP
attribute provides protection against overflow of the stack pointer.
If a thread's stack is created with guard protection, the
implementation allocates extra memory at the overflow end of the stack
as a buffer against stack overflow of the stack pointer. If
an application overflows into this buffer an error shall result (possibly
in a SIGSEGV signal being delivered to the thread).
.LP
A conforming implementation may round up the value contained in \fIguardsize\fP
to a multiple of the configurable system
variable {PAGESIZE} (see \fI<sys/mman.h>\fP). If an implementation
rounds up the
value of \fIguardsize\fP to a multiple of {PAGESIZE}, a call to \fIpthread_attr_getguardsize\fP()
specifying \fIattr\fP shall
store in the \fIguardsize\fP parameter the guard size specified by
the previous \fIpthread_attr_setguardsize\fP() function
call.
.LP
The default value of the \fIguardsize\fP attribute is {PAGESIZE} bytes.
The actual value of {PAGESIZE} is
implementation-defined.
.LP
If the \fIstackaddr\fP or \fIstack\fP attribute has been set (that
is, the caller is allocating and managing its own thread
stacks), the \fIguardsize\fP attribute shall be ignored and no protection
shall be provided by the implementation. It is the
responsibility of the application to manage stack overflow along with
stack allocation and management in this case.
.SH RETURN VALUE
.LP
If successful, the \fIpthread_attr_getguardsize\fP() and \fIpthread_attr_setguardsize\fP()
functions shall return zero;
otherwise, an error number shall be returned to indicate the error.
.SH ERRORS
.LP
The \fIpthread_attr_getguardsize\fP() and \fIpthread_attr_setguardsize\fP()
functions shall fail if:
.TP 7
.B EINVAL
The attribute \fIattr\fP is invalid.
.TP 7
.B EINVAL
The parameter \fIguardsize\fP is invalid.
.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
None.
.SH RATIONALE
.LP
The \fIguardsize\fP attribute is provided to the application for two
reasons:
.IP " 1." 4
Overflow protection can potentially result in wasted system resources.
An application that creates a large number of threads,
and which knows its threads never overflow their stack, can save system
resources by turning off guard areas.
.LP
.IP " 2." 4
When threads allocate large data structures on the stack, large guard
areas may be needed to detect stack overflow.
.LP
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP,
\fI<sys/mman.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 .