# pthread_attr_setguardsize

## NAME



           pthread_attr_setguardsize, pthread_attr_getguardsize - set/get
           guard size attribute in thread attributes object
    


## LIBRARY



           POSIX threads library (_libpthread_ , _-lpthread_)
    


## SYNOPSIS



           **#include <pthread.h>**
    
           **int pthread_attr_setguardsize(pthread_attr_t ***_attr_**, size_t** _guardsize_**);**
           **int pthread_attr_getguardsize(const pthread_attr_t *restrict** _attr_**,**
                                         **size_t *restrict** _guardsize_**);**
    


## DESCRIPTION



           The **pthread_attr_setguardsize**() function sets the guard size
           attribute of the thread attributes object referred to by _attr_ to
           the value specified in _guardsize_.
    
           If _guardsize_ is greater than 0, then for each new thread created
           using _attr_ the system allocates an additional region of at least
           _guardsize_ bytes at the end of the thread's stack to act as the
           guard area for the stack (but see BUGS).
    
           If _guardsize_ is 0, then new threads created with _attr_ will not
           have a guard area.
    
           The default guard size is the same as the system page size.
    
           If the stack address attribute has been set in _attr_ (using
           pthread_attr_setstack(3) or pthread_attr_setstackaddr(3)), meaning
           that the caller is allocating the thread's stack, then the guard
           size attribute is ignored (i.e., no guard area is created by the
           system): it is the application's responsibility to handle stack
           overflow (perhaps by using mprotect(2) to manually define a guard
           area at the end of the stack that it has allocated).
    
           The **pthread_attr_getguardsize**() function returns the guard size
           attribute of the thread attributes object referred to by _attr_ in
           the buffer pointed to by _guardsize_.
    


## RETURN VALUE



           On success, these functions return 0; on error, they return a
           nonzero error number.
    


## ERRORS



           POSIX.1 documents an **EINVAL** error if _attr_ or _guardsize_ is invalid.
           On Linux these functions always succeed (but portable and future-
           proof applications should nevertheless handle a possible error
           return).
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌──────────────────────────────────────┬───────────────┬─────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├──────────────────────────────────────┼───────────────┼─────────┤
           │ **pthread_attr_setguardsize**(),         │ Thread safety │ MT-Safe │
           │ **pthread_attr_getguardsize**()          │               │         │
           └──────────────────────────────────────┴───────────────┴─────────┘
    


## STANDARDS



           POSIX.1-2008.
    


## NOTES



           A guard area consists of virtual memory pages that are protected
           to prevent read and write access.  If a thread overflows its stack
           into the guard area, then, on most hard architectures, it receives
           a **SIGSEGV** signal, thus notifying it of the overflow.  Guard areas
           start on page boundaries, and the guard size is internally rounded
           up to the system page size when creating a thread.  (Nevertheless,
           **pthread_attr_getguardsize**() returns the guard size that was set by
           **pthread_attr_setguardsize**().)
    
           Setting a guard size of 0 may be useful to save memory in an
           application that creates many threads and knows that stack
           overflow can never occur.
    
           Choosing a guard size larger than the default size may be
           necessary for detecting stack overflows if a thread allocates
           large data structures on the stack.
    


## BUGS



           As at glibc 2.8, the NPTL threading implementation includes the
           guard area within the stack size allocation, rather than
           allocating extra space at the end of the stack, as POSIX.1
           requires.  (This can result in an **EINVAL** error from
           pthread_create(3) if the guard size value is too large, leaving no
           space for the actual stack.)
    
           The obsolete LinuxThreads implementation did the right thing,
           allocating extra space at the end of the stack for the guard area.
    


## EXAMPLES



           See pthread_getattr_np(3).
    


* * *