PTHREAD_ATTR_GETGUARDSIZE(3P)                       POSIX Programmer's Manual                      PTHREAD_ATTR_GETGUARDSIZE(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       pthread_attr_getguardsize, pthread_attr_setguardsize - get and set the thread guardsize attribute

SYNOPSIS
       #include <pthread.h>

       int pthread_attr_getguardsize(const pthread_attr_t *restrict attr,
              size_t *restrict guardsize);
       int pthread_attr_setguardsize(pthread_attr_t *attr,
              size_t guardsize);


DESCRIPTION
       The  pthread_attr_getguardsize()  function  shall get the guardsize attribute in the attr object. This attribute shall be
       returned in the guardsize parameter.

       The pthread_attr_setguardsize() function shall set the guardsize attribute in the attr object.  The  new  value  of  this
       attribute  shall  be  obtained from the guardsize parameter. If guardsize is zero, a guard area shall not be provided for
       threads created with attr. If guardsize is greater than zero, a guard area of at least size guardsize bytes shall be pro-
       vided for each thread created with attr.

       The  guardsize attribute controls the size of the guard area for the created thread's stack. The guardsize attribute pro-
       vides protection against overflow of the stack pointer.  If a thread's stack is created with guard protection, the imple-
       mentation  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).

       A  conforming implementation may round up the value contained in guardsize to a multiple of the configurable system vari-
       able {PAGESIZE} (see <sys/mman.h>). If an implementation rounds up the value of guardsize to a multiple of {PAGESIZE},  a
       call  to  pthread_attr_getguardsize()  specifying attr shall store in the guardsize parameter the guard size specified by
       the previous pthread_attr_setguardsize() function call.

       The default value of the guardsize attribute is {PAGESIZE} bytes.  The actual  value  of  {PAGESIZE}  is  implementation-
       defined.

       If  the stackaddr or stack attribute has been set (that is, the caller is allocating and managing its own thread stacks),
       the guardsize attribute shall be ignored and no protection shall be provided by the implementation. It is  the  responsi-
       bility of the application to manage stack overflow along with stack allocation and management in this case.

RETURN VALUE
       If successful, the pthread_attr_getguardsize() and pthread_attr_setguardsize() functions shall return zero; otherwise, an
       error number shall be returned to indicate the error.

ERRORS
       The pthread_attr_getguardsize() and pthread_attr_setguardsize() functions shall fail if:

       EINVAL The attribute attr is invalid.

       EINVAL The parameter guardsize is invalid.


       These functions shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

RATIONALE
       The guardsize attribute is provided to the application for two reasons:

        1. 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.

        2. When threads allocate large data structures on the stack, large guard areas may be needed to detect stack overflow.

FUTURE DIRECTIONS
       None.

SEE ALSO
       The Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>, <sys/mman.h>

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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                 PTHREAD_ATTR_GETGUARDSIZE(3P)