VMS Help POSIX Threads, PTHREAD routines, pthread_attr_setguardsize  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Changes the guardsize attribute of the specified thread
    attributes object.

1 - C Binding

    #include <pthread.h>

    int
    pthread_attr_setguardsize (
             pthread_attr_t   *attr,
             size_t   guardsize);

2 - Arguments

 attr

    Address of the thread attributes object whose guardsize attribute
    is to be modified.

 guardsize

    New value for the guardsize attribute of the thread attributes
    object specified by attr.

3 - 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
    nondefault 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 the
    Threads Library allocates at the overflow end of the thread's
    stack, following the thread's overflow warning area. If the
    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 this guide's platform-specific
    appendixes.

    After this routine is called, due to platform-specific factors
    the Threads Library might reserve a larger guard area for the
    new thread than was specified in the guardsize argument. See this
    guide's platform-specific appendixes for more information.

    The Threads Library allows your program to specify the size of a
    thread stack's guard area for two reasons:

    o  When a thread allocates large data structures on its stack, a
       guard area with a size greater than the default size might be
       required to detect stack overflow.

    o  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()
    routine), this routine ignores the object's guardsize attribute
    and provides no thread stack overflow warning or guard area for
    the new thread.

4 - Return Values

    If an error condition occurs, this routine returns an integer
    value indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The argument attr is not a valid thread attributes
                object, or the argument guardsize contains an invalid
                value.

5 - Associated Routines

       pthread_attr_init()
       pthread_attr_getguardsize()
       pthread_attr_setstacksize()
       pthread_create()