pthread_attr_getguardsize.3p (5972B)
- '\" et
- .TH PTHREAD_ATTR_GETGUARDSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH 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.
- .\"
- .SH NAME
- .ad l
- pthread_attr_getguardsize,
- pthread_attr_setguardsize
- \(em get and set the thread guardsize attribute
- .ad b
- .SH SYNOPSIS
- .LP
- .nf
- #include <pthread.h>
- .P
- int pthread_attr_getguardsize(const pthread_attr_t *restrict \fIattr\fP,
- size_t *restrict \fIguardsize\fP);
- int pthread_attr_setguardsize(pthread_attr_t *\fIattr\fP,
- size_t \fIguardsize\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIpthread_attr_getguardsize\fR()
- function shall get the
- .IR guardsize
- attribute in the
- .IR attr
- object. This attribute shall be returned in the
- .IR guardsize
- parameter.
- .P
- The
- \fIpthread_attr_setguardsize\fR()
- function shall set the
- .IR guardsize
- attribute in the
- .IR attr
- object. The new value of this attribute shall be obtained from the
- .IR guardsize
- parameter. If
- .IR guardsize
- is zero, a guard area shall not be provided for threads created with
- .IR attr .
- If
- .IR guardsize
- is greater than zero, a guard area of at least size
- .IR guardsize
- bytes shall be provided for each thread created with
- .IR attr .
- .P
- The
- .IR guardsize
- attribute controls the size of the guard area for the created thread's
- stack. The
- .IR 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).
- .P
- A conforming implementation may round up the value contained in
- .IR guardsize
- to a multiple of the configurable system variable
- {PAGESIZE}
- (see
- .IR <sys/mman.h> ).
- If an implementation rounds up the value of
- .IR guardsize
- to a multiple of
- {PAGESIZE},
- a call to
- \fIpthread_attr_getguardsize\fR()
- specifying
- .IR attr
- shall store in the
- .IR guardsize
- parameter the guard size specified by the previous
- \fIpthread_attr_setguardsize\fR()
- function call.
- .P
- The default value of the
- .IR guardsize
- attribute is implementation-defined.
- .P
- If the
- .IR stackaddr
- attribute has been set (that is, the caller is allocating and managing
- its own thread stacks), the
- .IR 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.
- .P
- The behavior is undefined if the value specified by the
- .IR attr
- argument to
- \fIpthread_attr_getguardsize\fR()
- or
- \fIpthread_attr_setguardsize\fR()
- does not refer to an initialized thread attributes object.
- .SH "RETURN VALUE"
- If successful, the
- \fIpthread_attr_getguardsize\fR()
- and
- \fIpthread_attr_setguardsize\fR()
- functions shall return zero; otherwise, an error number shall be
- returned to indicate the error.
- .SH ERRORS
- These functions shall fail if:
- .TP
- .BR EINVAL
- The parameter
- .IR guardsize
- is invalid.
- .P
- These functions shall not return an error code of
- .BR [EINTR] .
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Retrieving the guardsize Attribute"
- .P
- This example shows how to obtain the
- .IR guardsize
- attribute of a thread attribute object.
- .sp
- .RS 4
- .nf
- #include <pthread.h>
- .P
- pthread_attr_t thread_attr;
- size_t guardsize;
- int rc;
- .P
- /* code initializing thread_attr */
- \&...
- .P
- 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 */
- ...
- }
- }
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- The
- .IR guardsize
- attribute is provided to the application for two reasons:
- .IP " 1." 4
- 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.
- .IP " 2." 4
- When threads allocate large data structures on the stack, large guard
- areas may be needed to detect stack overflow.
- .P
- 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.
- .P
- If an implementation detects that the value specified by the
- .IR attr
- argument to
- \fIpthread_attr_getguardsize\fR()
- or
- \fIpthread_attr_setguardsize\fR()
- does not refer to an initialized thread attributes object, it is
- recommended that the function should fail and report an
- .BR [EINVAL]
- error.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<pthread.h>\fP",
- .IR "\fB<sys_mman.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .