.\" $OpenBSD: pthread_attr_setstack.3,v 1.5 2018/04/12 17:13:34 deraadt Exp $
.\" Manual page derived from TOG's UNIX98 documentation.
.\"
.\"  David Leonard, 2000. Public Domain.
.\"
.Dd $Mdocdate: April 12 2018 $
.Dt PTHREAD_ATTR_SETSTACK 3
.Os
.Sh NAME
.Nm pthread_attr_setstack ,
.Nm pthread_attr_getstack
.Nd set and get stack attributes
.Sh SYNOPSIS
.In pthread.h
.Ft int
.Fn pthread_attr_setstack "pthread_attr_t *attr" "void *stackaddr" "size_t stacksize"
.Ft int
.Fn pthread_attr_getstack "const pthread_attr_t *attr" "void **stackaddr" "size_t *stacksize"
.Sh DESCRIPTION
The functions
.Fn pthread_attr_setstack
and
.Fn pthread_attr_getstack ,
respectively, set and get the thread
creation
.Va stackaddr
and
.Va stacksize
attributes in the
.Fa attr
object.
.Pp
The stack attributes specify the area of storage to be used for the
created thread's stack.
The base (lowest addressable byte) of the storage shall be
.Va stackaddr ,
and the size of the storage shall be
.Va stacksize
bytes.
The stacksize shall be at least
.Dv PTHREAD_STACK_MIN .
.Pp
On
.Ox
the provided stack must be page-aligned.
It will be replaced (meaning zeroed) with a new
.Ar MAP_ANON | Ar MAP_STACK
mapping.
It is recommended that the initial mapping be allocated using
an allocator which has a matching deallocator that discards whole
pages, to clear the
.Ar MAP_STACK
attribute afterwards.
.Sh RETURN VALUES
Upon successful completion,
.Fn pthread_attr_setstack
and
.Fn pthread_attr_getstack
return a value of 0.
Otherwise, an error number is returned to indicate the error.
.Pp
The
.Fn pthread_attr_getstack
function stores the
.Va stackaddr
attribute value in
.Fa stackaddr
and the
.Va stacksize
attribute value in
.Fa stacksize
if successful.
.Sh ERRORS
The
.Fn pthread_attr_setstack
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The value of
.Fa stacksize
is less than
.Dv PTHREAD_STACK_MIN
or exceeds a system-imposed limit or the value of
.Fa stackaddr
is
.Dv NULL .
.El
.Pp
These functions will not return an error code of
.Bq Er EINTR .
.Sh SEE ALSO
.Xr pthread_attr_init 3 ,
.Xr pthread_attr_setdetachstate 3 ,
.Xr pthread_attr_setguardsize 3 ,
.Xr pthread_attr_setstackaddr 3 ,
.Xr pthread_attr_setstacksize 3 ,
.Xr pthread_create 3 ,
.Xr pthreads 3
.Sh STANDARDS
.Fn pthread_attr_setstack
and
.Fn pthread_attr_getstack
conform to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1, 2004 Edition.