1.\" $NetBSD: pthread_attr.3,v 1.21 2010/07/09 08:51:28 jruoho Exp $ 2.\" 3.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. 28.\" All rights reserved. 29.\" 30.\" Redistribution and use in source and binary forms, with or without 31.\" modification, are permitted provided that the following conditions 32.\" are met: 33.\" 1. Redistributions of source code must retain the above copyright 34.\" notice(s), this list of conditions and the following disclaimer as 35.\" the first lines of this file unmodified other than the possible 36.\" addition of one or more copyright notices. 37.\" 2. Redistributions in binary form must reproduce the above copyright 38.\" notice(s), this list of conditions and the following disclaimer in 39.\" the documentation and/or other materials provided with the 40.\" distribution. 41.\" 42.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 43.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 45.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 46.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 47.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 48.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 49.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 50.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 51.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 52.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 53.\" 54.\" $FreeBSD: src/lib/libpthread/man/pthread_attr.3,v 1.11 2002/09/16 19:29:28 mini Exp $ 55.\" 56.Dd July 9, 2010 57.Dt PTHREAD_ATTR 3 58.Os 59.Sh NAME 60.Nm pthread_attr_init , 61.Nm pthread_attr_destroy 62.Nd thread attribute operations 63.Sh LIBRARY 64.Lb libpthread 65.Sh SYNOPSIS 66.In pthread.h 67.Ft int 68.Fn pthread_attr_init "pthread_attr_t *attr" 69.Ft int 70.Fn pthread_attr_destroy "pthread_attr_t *attr" 71.Sh DESCRIPTION 72Thread attributes are used to specify parameters to 73.Fn pthread_create . 74One attribute object can be used in multiple calls to 75.Fn pthread_create , 76with or without modifications between the calls. 77The 78.Vt pthread_attr_t 79type is an opaque representation of the thread attributes; 80any access to the object other than via the described 81.Fn pthread_attr_* 82functions may result in undefined behavior. 83.Pp 84The 85.Fn pthread_attr_init 86function initializes 87.Fa attr 88with the default thread attributes used in the implementation. 89Depending on the implementation, undefined behavior may follow 90if an uninitialized thread attribute object is used with some of 91the thread attribute functions. 92It is therefore a good practice to always use 93.Fn pthread_attr_init , 94even if this might be unnecessary. 95Undefined behavior may also follow if an already initialized 96.Fa attr 97is used with 98.Fn pthread_attr_init . 99.Pp 100When the attribute object is no longer needed, 101it should be destroyed by using 102.Fn pthread_attr_destroy . 103The function has no effect on threads that 104were created by using a given attribute object. 105A destroyed 106.Fa attr 107can be reinitialized using 108.Fn pthread_attr_init , 109but all other actions with the destroyed object are unspecified. 110.Pp 111The following standard thread attribute functions are available: 112.Bl -column -offset indent "pthread_attr_getinheritsched " "XXX" 113.It Sy Function Ta Sy Description 114.It Xr pthread_attr_getdetachstate 3 Ta thread detach state 115.It Xr pthread_attr_getguardsize 3 Ta thread guard size 116.It Xr pthread_attr_getinheritsched 3 Ta inherit scheduler attribute 117.It Xr pthread_attr_getschedparam 3 Ta thread scheduling parameter 118.It Xr pthread_attr_getschedpolicy 3 Ta thread scheduling policy 119.It Xr pthread_attr_getscope 3 Ta thread contention scope 120.It Xr pthread_attr_getstack 3 Ta thread stack 121.It Xr pthread_attr_getstacksize 3 Ta thread stack size 122.It Xr pthread_attr_getstackaddr 3 Ta thread stack address 123.El 124.Pp 125Each listed 126.Fn pthread_attr_get* 127function contains a 128.Fn pthread_attr_set* 129counterpart. 130In addition, the following 131.Nx 132specific extensions are available: 133.Bl -column -offset indent "pthread_attr_getinheritsched " "XXX" 134.It Sy Function Ta Sy Description 135.It Xr pthread_attr_get_np 3 Ta attributes of a running thread 136.It Xr pthread_attr_getname_np 3 Ta descriptive name of an attribute 137.El 138.Sh RETURN VALUES 139If successful, these functions return 0. 140Otherwise, an error number is returned to indicate the error. 141.Sh ERRORS 142No errors are defined for 143.Fn pthread_attr_init 144and 145.Fn pthread_attr_destroy . 146.Sh SEE ALSO 147.Xr pthread_create 3 , 148.Xr pthread_join 3 149.Sh STANDARDS 150Both 151.Fn pthread_attr_init 152and 153.Fn pthread_attr_destroy 154conform to 155.St -p1003.1-2001 . 156