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