1.\" $OpenBSD: pthread_attr_setstack.3,v 1.6 2020/12/03 07:05:03 otto Exp $
2.\" Manual page derived from TOG's UNIX98 documentation.
3.\"
4.\"  David Leonard, 2000. Public Domain.
5.\"
6.Dd $Mdocdate: December 3 2020 $
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.
49The passed memory object should not be deallocated or reused,
50even when the thread using it has terminated.
51If there is no need for a specific memory object as stack,
52the
53.Xr pthread_attr_setstacksize 3
54function should be used.
55.Sh RETURN VALUES
56Upon successful completion,
57.Fn pthread_attr_setstack
58and
59.Fn pthread_attr_getstack
60return a value of 0.
61Otherwise, an error number is returned to indicate the error.
62.Pp
63The
64.Fn pthread_attr_getstack
65function stores the
66.Va stackaddr
67attribute value in
68.Fa stackaddr
69and the
70.Va stacksize
71attribute value in
72.Fa stacksize
73if successful.
74.Sh ERRORS
75The
76.Fn pthread_attr_setstack
77function will fail if:
78.Bl -tag -width Er
79.It Bq Er EINVAL
80The value of
81.Fa stacksize
82is less than
83.Dv PTHREAD_STACK_MIN
84or exceeds a system-imposed limit or the value of
85.Fa stackaddr
86is
87.Dv NULL .
88.El
89.Pp
90These functions will not return an error code of
91.Bq Er EINTR .
92.Sh SEE ALSO
93.Xr pthread_attr_init 3 ,
94.Xr pthread_attr_setdetachstate 3 ,
95.Xr pthread_attr_setguardsize 3 ,
96.Xr pthread_attr_setstackaddr 3 ,
97.Xr pthread_attr_setstacksize 3 ,
98.Xr pthread_create 3 ,
99.Xr pthreads 3
100.Sh STANDARDS
101.Fn pthread_attr_setstack
102and
103.Fn pthread_attr_getstack
104conform to ISO/IEC 9945-1 ANSI/IEEE
105.Pq Dq Tn POSIX
106Std 1003.1, 2004 Edition.
107