diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/pthread_attr_getguardsize.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/pthread_attr_getguardsize.3p | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/pthread_attr_getguardsize.3p b/man-pages-posix-2017/man3p/pthread_attr_getguardsize.3p new file mode 100644 index 0000000..ba2fb1b --- /dev/null +++ b/man-pages-posix-2017/man3p/pthread_attr_getguardsize.3p @@ -0,0 +1,217 @@ +'\" 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 . |