mirror of https://github.com/mkerrisk/man-pages
179 lines
5.4 KiB
Groff
179 lines
5.4 KiB
Groff
.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
|
|
.\" <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH PTHREAD_ATTR_SETGUARDSIZE 3 2015-08-08 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
pthread_attr_setguardsize, pthread_attr_getguardsize \- set/get guard size
|
|
attribute in thread attributes object
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <pthread.h>
|
|
|
|
.BI "int pthread_attr_setguardsize(pthread_attr_t *" attr \
|
|
", size_t " guardsize );
|
|
.BI "int pthread_attr_getguardsize(const pthread_attr_t *" attr \
|
|
", size_t *" guardsize );
|
|
.sp
|
|
Compile and link with \fI\-pthread\fP.
|
|
.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 .
|
|
|
|
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).
|
|
|
|
If
|
|
.I guardsize
|
|
is 0, then new threads created with
|
|
.I attr
|
|
will not have a guard area.
|
|
|
|
The default guard size is the same as the system page size.
|
|
|
|
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).
|
|
|
|
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 VERSIONS
|
|
These functions are provided by glibc since version 2.1.
|
|
.SH ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.TS
|
|
allbox;
|
|
lbw28 lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR pthread_attr_setguardsize (),
|
|
.BR pthread_attr_getguardsize ()
|
|
T} Thread safety MT-Safe
|
|
.TE
|
|
.SH CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008.
|
|
.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 ().)
|
|
|
|
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.
|
|
|
|
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.)
|
|
|
|
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:
|
|
.\" http://sources.redhat.com/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 EXAMPLE
|
|
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)
|