1.\" $OpenBSD: pthread_attr_setstack.3,v 1.5 2018/04/12 17:13:34 deraadt Exp $
2.\" Manual page derived from TOG's UNIX98 documentation.
3.\"
4.\"  David Leonard, 2000. Public Domain.
5.\"
6.Dd $Mdocdate: April 12 2018 $
7.Dt PTHREAD_ATTR_SETSTACK 3
8.Os
9.Sh NAME
10.Nm pthread_attr_setstack ,
11.Nm pthread_attr_getstack
12.Nd set and get stack attributes
13.Sh SYNOPSIS
14.In pthread.h
15.Ft int
16.Fn pthread_attr_setstack "pthread_attr_t *attr" "void *stackaddr" "size_t stacksize"
17.Ft int
18.Fn pthread_attr_getstack "const pthread_attr_t *attr" "void **stackaddr" "size_t *stacksize"
19.Sh DESCRIPTION
20The functions
21.Fn pthread_attr_setstack
22and
23.Fn pthread_attr_getstack ,
24respectively, set and get the thread
25creation
26.Va stackaddr
27and
28.Va stacksize
29attributes in the
30.Fa attr
31object.
32.Pp
33The stack attributes specify the area of storage to be used for the
34created thread's stack.
35The base (lowest addressable byte) of the storage shall be
36.Va stackaddr ,
37and the size of the storage shall be
38.Va stacksize
39bytes.
40The stacksize shall be at least
41.Dv PTHREAD_STACK_MIN .
42.Pp
43On
44.Ox
45the provided stack must be page-aligned.
46It will be replaced (meaning zeroed) with a new
47.Ar MAP_ANON | Ar MAP_STACK
48mapping.
49It is recommended that the initial mapping be allocated using
50an allocator which has a matching deallocator that discards whole
51pages, to clear the
52.Ar MAP_STACK
53attribute afterwards.
54.Sh RETURN VALUES
55Upon successful completion,
56.Fn pthread_attr_setstack
57and
58.Fn pthread_attr_getstack
59return a value of 0.
60Otherwise, an error number is returned to indicate the error.
61.Pp
62The
63.Fn pthread_attr_getstack
64function stores the
65.Va stackaddr
66attribute value in
67.Fa stackaddr
68and the
69.Va stacksize
70attribute value in
71.Fa stacksize
72if successful.
73.Sh ERRORS
74The
75.Fn pthread_attr_setstack
76function will fail if:
77.Bl -tag -width Er
78.It Bq Er EINVAL
79The value of
80.Fa stacksize
81is less than
82.Dv PTHREAD_STACK_MIN
83or exceeds a system-imposed limit or the value of
84.Fa stackaddr
85is
86.Dv NULL .
87.El
88.Pp
89These functions will not return an error code of
90.Bq Er EINTR .
91.Sh SEE ALSO
92.Xr pthread_attr_init 3 ,
93.Xr pthread_attr_setdetachstate 3 ,
94.Xr pthread_attr_setguardsize 3 ,
95.Xr pthread_attr_setstackaddr 3 ,
96.Xr pthread_attr_setstacksize 3 ,
97.Xr pthread_create 3 ,
98.Xr pthreads 3
99.Sh STANDARDS
100.Fn pthread_attr_setstack
101and
102.Fn pthread_attr_getstack
103conform to ISO/IEC 9945-1 ANSI/IEEE
104.Pq Dq Tn POSIX
105Std 1003.1, 2004 Edition.
106