pthread_attr_setguardsize(3)pthread_attr_setguardsize(3)NAMEpthread_attr_setguardsize - Changes the guardsize attribute of the
specified thread attributes object
SYNOPSIS
#include <pthread.h>
int pthread_attr_setguardsize(
pthread_attr_t *attr,
size_t guardsize );
LIBRARY
DECthreads POSIX 1003.1c Library (libpthread.so)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
PARAMETERS
Address of the thread attributes object whose guardsize attribute is to
be modified. New value for the guardsize attribute of the thread
attributes object specified by attr.
DESCRIPTION
This routine uses the value specified in the guardsize argument to set
the guardsize attribute of the thread attributes object specified in
the attr argument.
When creating a thread, use a thread attributes object to specify non‐
default values for thread attributes. The guardsize attribute of a
thread attributes object specifies the minimum size (in bytes) of the
guard area for the stack of a new thread.
A guard area, with its associated overflow warning area, can help a
multithreaded program detect overflow of a thread's stack. A guard area
is a region of no-access memory that DECthreads allocates at the over‐
flow end of the thread's stack, following the thread's overflow warning
area. If any thread attempts to write in the overflow warning area, a
stack overflow exception occurs. Your program can catch this exception
and continue processing as long as the thread does not attempt to write
in the guard area. When any thread attempts to access a memory location
within the guard area, a memory addressing violation occurs without the
possibility of recovery.
A new thread can be created with a default guardsize attribute value.
This value is platform dependent, but will always be at least one
“hardware protection unit” (that is, at least one page). For more
information, see the platform-specific appendixes of Guide to DEC‐
threads.
After this routine is called, due to platform-specific factors DEC‐
threads might reserve a larger guard area for the new thread than was
specified in the guardsize argument. For more information, see the
platform-specific appendixes of Guide to DECthreads.
DECthreads allows your program to specify the size of a thread stack's
guard area for two reasons: When a thread allocates large data struc‐
tures on its stack, a guard area with a size greater than the default
size might be required to detect stack overflow. Overflow protection
of a thread's stack can potentially waste system resources, such as for
an application that creates a large number of threads that will never
overflow their stacks. Your multithreaded program can conserve system
resources by “turning off” a thread's stack guard area--that is, by
specifying a guardsize attribute of zero.
If a thread is created using a thread attributes object whose stackaddr
attribute is set (using the pthread_attr_setstackaddr(3) routine), this
routine ignores the object's guardsize attribute and provides no thread
stack guard area for the new thread.
RETURN VALUES
If an error condition occurs, this routine returns an integer value
indicating the type of error. Possible return values are as follows:
Successful completion. The argument attr is not a valid thread
attributes object, or the argument guardsize contains an invalid value.
ERRORS
None
SEE ALSO
Functions: pthread_attr_init(3), pthread_attr_getguardsize(3),
pthread_attr_setstacksize(3), pthread_create(3)
Manuals: Guide to DECthreads and Programmer's Guide
pthread_attr_setguardsize(3)