'\" t
.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
.\" <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH pthread_attr_setstacksize 3 (date) "Linux man-pages (unreleased)"
.SH NAME
pthread_attr_setstacksize, pthread_attr_getstacksize \- set/get stack 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_setstacksize(pthread_attr_t *" attr \
", size_t " stacksize );
.BI "int pthread_attr_getstacksize(const pthread_attr_t *restrict " attr ,
.BI " size_t *restrict " stacksize );
.fi
.SH DESCRIPTION
The
.BR pthread_attr_setstacksize ()
function sets the stack size attribute of the
thread attributes object referred to by
.I attr
to the value specified in
.IR stacksize .
.P
The stack size attribute determines the minimum size (in bytes) that
will be allocated for threads created using the thread attributes object
.IR attr .
.P
The
.BR pthread_attr_getstacksize ()
function returns the stack size attribute of the
thread attributes object referred to by
.I attr
in the buffer pointed to by
.IR stacksize .
.SH RETURN VALUE
On success, these functions return 0;
on error, they return a nonzero error number.
.SH ERRORS
.BR pthread_attr_setstacksize ()
can fail with the following error:
.TP
.B EINVAL
The stack size is less than
.B PTHREAD_STACK_MIN
(16384) bytes.
.P
On some systems,
.\" e.g., MacOS
.BR pthread_attr_setstacksize ()
can fail with the error
.B EINVAL
if
.I stacksize
is not a multiple of the system page size.
.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_setstacksize (),
.BR pthread_attr_getstacksize ()
T} Thread safety MT-Safe
.TE
.SH VERSIONS
These functions are provided since glibc 2.1.
.SH STANDARDS
POSIX.1-2001, POSIX.1-2008.
.SH NOTES
For details on the default stack size of new threads, see
.BR pthread_create (3).
.P
A thread's stack size is fixed at the time of thread creation.
Only the main thread can dynamically grow its stack.
.P
The
.BR pthread_attr_setstack (3)
function allows an application to set both the size and location
of a caller-allocated stack that is to be used by a thread.
.SH BUGS
As at glibc 2.8,
if the specified
.I stacksize
is not a multiple of
.B STACK_ALIGN
(16 bytes on most architectures), it may be rounded
.IR downward ,
in violation of POSIX.1, which says that the allocated stack will
be at least
.I stacksize
bytes.
.SH EXAMPLES
See
.BR pthread_create (3).
.SH SEE ALSO
.BR getrlimit (2),
.BR pthread_attr_init (3),
.BR pthread_attr_setguardsize (3),
.BR pthread_attr_setstack (3),
.BR pthread_create (3),
.BR pthreads (7)
