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