xref: /freebsd/share/man/man3/pthread_attr.3 (revision 9a14aa017b21c292740c00ee098195cd46642730)
1.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice(s), this list of conditions and the following disclaimer as
9.\"    the first lines of this file unmodified other than the possible
10.\"    addition of one or more copyright notices.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice(s), this list of conditions and the following disclaimer in
13.\"    the documentation and/or other materials provided with the
14.\"    distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
20.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
23.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
25.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
26.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27.\"
28.\" $FreeBSD$
29.Dd January 8, 2010
30.Dt PTHREAD_ATTR 3
31.Os
32.Sh NAME
33.Nm pthread_attr_init ,
34.Nm pthread_attr_destroy ,
35.Nm pthread_attr_setstack ,
36.Nm pthread_attr_getstack ,
37.Nm pthread_attr_setstacksize ,
38.Nm pthread_attr_getstacksize ,
39.Nm pthread_attr_setguardsize ,
40.Nm pthread_attr_getguardsize ,
41.Nm pthread_attr_setstackaddr ,
42.Nm pthread_attr_getstackaddr ,
43.Nm pthread_attr_setdetachstate ,
44.Nm pthread_attr_getdetachstate ,
45.Nm pthread_attr_setinheritsched ,
46.Nm pthread_attr_getinheritsched ,
47.Nm pthread_attr_setschedparam ,
48.Nm pthread_attr_getschedparam ,
49.Nm pthread_attr_setschedpolicy ,
50.Nm pthread_attr_getschedpolicy ,
51.Nm pthread_attr_setscope ,
52.Nm pthread_attr_getscope
53.Nd thread attribute operations
54.Sh LIBRARY
55.Lb libpthread
56.Sh SYNOPSIS
57.In pthread.h
58.Ft int
59.Fn pthread_attr_init "pthread_attr_t *attr"
60.Ft int
61.Fn pthread_attr_destroy "pthread_attr_t *attr"
62.Ft int
63.Fn pthread_attr_setstack "pthread_attr_t *attr" " void *stackaddr" "size_t stacksize"
64.Ft int
65.Fn pthread_attr_getstack "const pthread_attr_t * restrict attr" "void ** restrict stackaddr" "size_t * restrict stacksize"
66.Ft int
67.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
68.Ft int
69.Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
70.Ft int
71.Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize"
72.Ft int
73.Fn pthread_attr_getguardsize "const pthread_attr_t *attr" "size_t *guardsize"
74.Ft int
75.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
76.Ft int
77.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
78.Ft int
79.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
80.Ft int
81.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
82.Ft int
83.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
84.Ft int
85.Fn pthread_attr_getinheritsched "const pthread_attr_t *attr" "int *inheritsched"
86.Ft int
87.Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param"
88.Ft int
89.Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *param"
90.Ft int
91.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
92.Ft int
93.Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
94.Ft int
95.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
96.Ft int
97.Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
98.Sh DESCRIPTION
99Thread attributes are used to specify parameters to
100.Fn pthread_create .
101One attribute object can be used in multiple calls to
102.Fn pthread_create ,
103with or without modifications between calls.
104.Pp
105The
106.Fn pthread_attr_init
107function initializes
108.Fa attr
109with all the default thread attributes.
110.Pp
111The
112.Fn pthread_attr_destroy
113function destroys
114.Fa attr .
115.Pp
116The
117.Fn pthread_attr_set*
118functions set the attribute that corresponds to each function name.
119.Pp
120The
121.Fn pthread_attr_get*
122functions copy the value of the attribute that corresponds to each function name
123to the location pointed to by the second function parameter.
124.Sh RETURN VALUES
125If successful, these functions return 0.
126Otherwise, an error number is returned to indicate the error.
127.Sh ERRORS
128The
129.Fn pthread_attr_init
130function will fail if:
131.Bl -tag -width Er
132.It Bq Er ENOMEM
133Out of memory.
134.El
135.Pp
136The
137.Fn pthread_attr_destroy
138function will fail if:
139.Bl -tag -width Er
140.It Bq Er EINVAL
141Invalid value for
142.Fa attr .
143.El
144.Pp
145The
146.Fn pthread_attr_setstacksize
147and
148.Fn pthread_attr_setstack
149functions will fail if:
150.Bl -tag -width Er
151.It Bq Er EINVAL
152.Fa stacksize
153is less than
154.Dv PTHREAD_STACK_MIN .
155.El
156.Pp
157The
158.Fn pthread_attr_setdetachstate
159function will fail if:
160.Bl -tag -width Er
161.It Bq Er EINVAL
162Invalid value for
163.Fa detachstate .
164.El
165.Pp
166The
167.Fn pthread_attr_setinheritsched
168function will fail if:
169.Bl -tag -width Er
170.It Bq Er EINVAL
171Invalid value for
172.Fa attr .
173.El
174.Pp
175The
176.Fn pthread_attr_setschedparam
177function will fail if:
178.Bl -tag -width Er
179.It Bq Er EINVAL
180Invalid value for
181.Fa attr .
182.It Bq Er ENOTSUP
183Invalid value for
184.Fa param .
185.El
186.Pp
187The
188.Fn pthread_attr_setschedpolicy
189function will fail if:
190.Bl -tag -width Er
191.It Bq Er EINVAL
192Invalid value for
193.Fa attr .
194.It Bq Er ENOTSUP
195Invalid or unsupported value for
196.Fa policy .
197.El
198.Pp
199The
200.Fn pthread_attr_setscope
201function will fail if:
202.Bl -tag -width Er
203.It Bq Er EINVAL
204Invalid value for
205.Fa attr .
206.It Bq Er ENOTSUP
207Invalid or unsupported value for
208.Fa contentionscope .
209.El
210.Sh SEE ALSO
211.Xr pthread_attr_get_np 3 ,
212.Xr pthread_attr_affinity_np 3 ,
213.Xr pthread_create 3
214.Sh STANDARDS
215.Fn pthread_attr_init ,
216.Fn pthread_attr_destroy ,
217.Fn pthread_attr_setstacksize ,
218.Fn pthread_attr_getstacksize ,
219.Fn pthread_attr_setstackaddr ,
220.Fn pthread_attr_getstackaddr ,
221.Fn pthread_attr_setdetachstate ,
222and
223.Fn pthread_attr_getdetachstate
224functions conform to
225.St -p1003.1-96
226.Pp
227The
228.Fn pthread_attr_setinheritsched ,
229.Fn pthread_attr_getinheritsched ,
230.Fn pthread_attr_setschedparam ,
231.Fn pthread_attr_getschedparam ,
232.Fn pthread_attr_setschedpolicy ,
233.Fn pthread_attr_getschedpolicy ,
234.Fn pthread_attr_setscope ,
235and
236.Fn pthread_attr_getscope
237functions conform to
238.St -susv2
239