# pthread_attr_getguardsize

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


## 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 provided 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 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).
    
           A  conforming  implementation  may round up the value contained in
           _guardsize_ to  a  multiple  of  the  configurable  system  variable
           {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  implementation-
           defined.
    
           If  the  _stackaddr_  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 responsibility of the application to
           manage stack overflow along with stack allocation  and  management
           in this case.
    
           The  behavior  is  undefined  if  the  value specified by the _attr_
           argument         to         _pthread_attr_getguardsize_()         or
           _pthread_attr_setguardsize_()  does  not  refer  to  an  initialized
           thread attributes object.
    


## 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



           These functions shall fail if:
    
           **EINVAL** The parameter _guardsize_ is invalid.
    
           These functions shall not return an error code of **[EINTR]**.
    
           _The following sections are informative._
    


## EXAMPLES



       **Retrieving the guardsize Attribute**
           This example shows how to obtain the _guardsize_ attribute of a
           thread attribute object.
    
               #include <pthread.h>
    
               pthread_attr_t thread_attr;
               size_t  guardsize;
               int     rc;
    
               /* code initializing thread_attr */
               ...
    
               rc = pthread_attr_getguardsize (&thread_attr, &guardsize);
               if (rc != 0)  {
                   /* handle error */
                   ...
               }
               else {
                   if (guardsize > 0) {
                   /* a guard area of at least guardsize bytes is provided */
                   ...
                   }
                   else {
                   /* no guard area provided */
                   ...
                   }
               }
    


## 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.
    
           The default size of the guard area is left implementation-defined
           since on systems supporting very large page sizes, the overhead
           might be substantial if at least one guard page is required by
           default.
    
           If an implementation detects that the value specified by the _attr_
           argument to _pthread_attr_getguardsize_() or
           _pthread_attr_setguardsize_() does not refer to an initialized
           thread attributes object, it is recommended that the function
           should fail and report an **[EINVAL]** error.
    


## FUTURE DIRECTIONS



           None.
    


* * *