Move pthread* manpages to lib/libpthread as they are not libc_r specific.
[dragonfly.git] / lib / libpthread / pthread_attr.3
CommitLineData
984263bc
MD
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: src/lib/libc_r/man/pthread_attr.3,v 1.4.2.7 2003/03/04 16:51:13 phantom Exp $
1de703da 29.\" $DragonFly: src/lib/libc_r/man/pthread_attr.3,v 1.2 2003/06/17 04:26:47 dillon Exp $
984263bc
MD
30.Dd April 28, 2000
31.Dt PTHREAD_ATTR 3
32.Os
33.Sh NAME
34.Nm pthread_attr_init ,
35.Nm pthread_attr_destroy ,
36.Nm pthread_attr_setstack ,
37.Nm pthread_attr_getstack ,
38.Nm pthread_attr_setstacksize ,
39.Nm pthread_attr_getstacksize ,
40.Nm pthread_attr_setstackaddr ,
41.Nm pthread_attr_getstackaddr ,
42.Nm pthread_attr_setdetachstate ,
43.Nm pthread_attr_getdetachstate ,
44.Nm pthread_attr_setinheritsched ,
45.Nm pthread_attr_getinheritsched ,
46.Nm pthread_attr_setschedparam ,
47.Nm pthread_attr_getschedparam ,
48.Nm pthread_attr_setschedpolicy ,
49.Nm pthread_attr_getschedpolicy ,
50.Nm pthread_attr_setscope ,
51.Nm pthread_attr_getscope
52.Nd thread attribute operations
53.Sh LIBRARY
54.Lb libc_r
55.Sh SYNOPSIS
56.In pthread.h
57.Ft int
58.Fn pthread_attr_init "pthread_attr_t *attr"
59.Ft int
60.Fn pthread_attr_destroy "pthread_attr_t *attr"
61.Ft int
8a6999e3 62.Fn pthread_attr_setstack "pthread_attr_t *attr" "void *stackaddr" "size_t stacksize"
984263bc
MD
63.Ft int
64.Fn pthread_attr_getstack "const pthread_attr_t * restrict attr" "void ** restrict stackaddr" "size_t * restrict stacksize"
65.Ft int
66.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
67.Ft int
68.Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
69.Ft int
70.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
71.Ft int
72.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
73.Ft int
74.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
75.Ft int
76.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
77.Ft int
78.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
79.Ft int
80.Fn pthread_attr_getinheritsched "const pthread_attr_t *attr" "int *inheritsched"
81.Ft int
82.Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param"
83.Ft int
84.Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *param"
85.Ft int
86.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
87.Ft int
88.Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
89.Ft int
90.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
91.Ft int
92.Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
93.Sh DESCRIPTION
94Thread attributes are used to specify parameters to
95.Fn pthread_create .
96One attribute object can be used in multiple calls to
97.Fn pthread_create ,
98with or without modifications between calls.
99.Pp
100The
101.Fn pthread_attr_init
102function initializes
103.Fa attr
104with all the default thread attributes.
105.Pp
106The
107.Fn pthread_attr_destroy
108function destroys
109.Fa attr .
110.Pp
111The
112.Fn pthread_attr_set*
113functions set the attribute that corresponds to each function name.
114.Pp
115The
116.Fn pthread_attr_get*
117functions copy the value of the attribute that corresponds to each function name
118to the location pointed to by the second function parameter.
119.Sh RETURN VALUES
120If successful, these functions return 0.
121Otherwise, an error number is returned to indicate the error.
122.Sh ERRORS
123.Fn pthread_attr_init
124will fail if:
125.Bl -tag -width Er
126.It Bq Er ENOMEM
127Out of memory.
128.El
129.Pp
130.Fn pthread_attr_destroy
131will fail if:
132.Bl -tag -width Er
133.It Bq Er EINVAL
134Invalid value for
135.Fa attr .
136.El
137.Pp
138The
139.Fn pthread_attr_setstacksize
140and
141.Fn pthread_attr_setstack
142functions will fail if:
143.Bl -tag -width Er
144.It Bq Er EINVAL
145.Fa stacksize
146is less than
147.Dv PTHREAD_STACK_MIN .
148.El
149.Pp
150.Fn pthread_attr_setdetachstate
151will fail if:
152.Bl -tag -width Er
153.It Bq Er EINVAL
154Invalid value for
155.Fa detachstate .
156.El
157.Pp
158.Fn pthread_attr_setinheritsched
159will fail if:
160.Bl -tag -width Er
161.It Bq Er EINVAL
162Invalid value for
163.Fa attr .
164.El
165.Pp
166.Fn pthread_attr_setschedparam
167will fail if:
168.Bl -tag -width Er
169.It Bq Er EINVAL
170Invalid value for
171.Fa attr .
172.It Bq Er ENOTSUP
173Invalid value for
174.Fa param .
175.El
176.Pp
177.Fn pthread_attr_setschedpolicy
178will fail if:
179.Bl -tag -width Er
180.It Bq Er EINVAL
181Invalid value for
182.Fa attr .
183.It Bq Er ENOTSUP
184Invalid or unsupported value for
185.Fa policy .
186.El
187.Pp
188.Fn pthread_attr_setscope
189will 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 contentionscope .
197.El
198.Sh SEE ALSO
199.Xr pthread_attr_get_np 3 ,
200.Xr pthread_create 3
201.Sh STANDARDS
202.Fn pthread_attr_init ,
203.Fn pthread_attr_destroy ,
204.Fn pthread_attr_setstacksize ,
205.Fn pthread_attr_getstacksize ,
206.Fn pthread_attr_setstackaddr ,
207.Fn pthread_attr_getstackaddr ,
208.Fn pthread_attr_setdetachstate ,
209and
210.Fn pthread_attr_getdetachstate
211conform to
212.St -p1003.1-96
213.Pp
214.Fn pthread_attr_setinheritsched ,
215.Fn pthread_attr_getinheritsched ,
216.Fn pthread_attr_setschedparam ,
217.Fn pthread_attr_getschedparam ,
218.Fn pthread_attr_setschedpolicy ,
219.Fn pthread_attr_getschedpolicy ,
220.Fn pthread_attr_setscope ,
221and
222.Fn pthread_attr_getscope
223conform to
224.St -susv2