diff options
Diffstat (limited to 'man/man3/pthread_attr_setguardsize.3')
| -rw-r--r-- | man/man3/pthread_attr_setguardsize.3 | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/man/man3/pthread_attr_setguardsize.3 b/man/man3/pthread_attr_setguardsize.3 new file mode 100644 index 0000000..0056650 --- /dev/null +++ b/man/man3/pthread_attr_setguardsize.3 @@ -0,0 +1,163 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setguardsize 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setguardsize, pthread_attr_getguardsize \- set/get guard size +attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_attr_setguardsize(pthread_attr_t *" attr \ +", size_t " guardsize ); +.BI "int pthread_attr_getguardsize(const pthread_attr_t *restrict " attr , +.BI " size_t *restrict " guardsize ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setguardsize () +function sets the guard size attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR guardsize . +.P +If +.I guardsize +is greater than 0, +then for each new thread created using +.I attr +the system allocates an additional region of at least +.I guardsize +bytes at the end of the thread's stack to act as the guard area +for the stack (but see BUGS). +.P +If +.I guardsize +is 0, then new threads created with +.I attr +will not have a guard area. +.P +The default guard size is the same as the system page size. +.P +If the stack address attribute has been set in +.I attr +(using +.BR pthread_attr_setstack (3) +or +.BR 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 +.BR mprotect (2) +to manually define a guard area at the end of the stack +that it has allocated). +.P +The +.BR pthread_attr_getguardsize () +function returns the guard size attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR guardsize . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +POSIX.1 documents an +.B EINVAL +error if +.I attr +or +.I guardsize +is invalid. +On Linux these functions always succeed +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setguardsize (), +.BR pthread_attr_getguardsize () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH 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 +.B 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, +.BR pthread_attr_getguardsize () +returns the guard size that was set by +.BR pthread_attr_setguardsize ().) +.P +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. +.P +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. +.SH 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 +.B EINVAL +error from +.BR pthread_create (3) +if the guard size value is too large, +leaving no space for the actual stack.) +.P +The obsolete LinuxThreads implementation did the right thing, +allocating extra space at the end of the stack for the guard area. +.\" glibc includes the guardsize within the allocated stack size, +.\" which looks pretty clearly to be in violation of POSIX. +.\" +.\" Filed bug, 22 Oct 2008: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6973 +.\" +.\" Older reports: +.\" https//bugzilla.redhat.com/show_bug.cgi?id=435337 +.\" Reportedly, LinuxThreads did the right thing, allocating +.\" extra space at the end of the stack: +.\" http://sourceware.org/ml/libc-alpha/2008-05/msg00086.html +.SH EXAMPLES +See +.BR pthread_getattr_np (3). +.SH SEE ALSO +.BR mmap (2), +.BR mprotect (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) |