lib/libpthread/pthread_attr.3

   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 .\"
   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 October 6, 2009
  57 .Dt PTHREAD_ATTR 3
  58 .Os
  59 .Sh NAME
  60 .Nm pthread_attr_init ,
  61 .Nm pthread_attr_destroy ,
  62 .Nm pthread_attr_setstacksize ,
  63 .Nm pthread_attr_getstacksize ,
  64 .Nm pthread_attr_setguardsize ,
  65 .Nm pthread_attr_getguardsize ,
  66 .Nm pthread_attr_setstackaddr ,
  67 .Nm pthread_attr_getstackaddr ,
  68 .Nm pthread_attr_setdetachstate ,
  69 .Nm pthread_attr_getdetachstate ,
  70 .Nm pthread_attr_setinheritsched ,
  71 .Nm pthread_attr_getinheritsched ,
  72 .Nm pthread_attr_setschedparam ,
  73 .Nm pthread_attr_getschedparam
  74 .Nm pthread_attr_setschedpolicy ,
  75 .Nm pthread_attr_getschedpolicy ,
  76 .Nm pthread_attr_setscope ,
  77 .Nm pthread_attr_getscope
  78 .Nd thread attribute operations
  79 .Sh LIBRARY
  80 .Lb libpthread
  81 .Sh SYNOPSIS
  82 .In pthread.h
  83 .Ft int
  84 .Fn pthread_attr_init "pthread_attr_t *attr"
  85 .Ft int
  86 .Fn pthread_attr_destroy "pthread_attr_t *attr"
  87 .Ft int
  88 .Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
  89 .Ft int
  90 .Fn pthread_attr_getstacksize "const pthread_attr_t * restrict attr" "size_t * restrict stacksize"
  91 .Ft int
  92 .Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize"
  93 .Ft int
  94 .Fn pthread_attr_getguardsize "const pthread_attr_t * restrict attr" "size_t * restrict guardsize"
  95 .Ft int
  96 .Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
  97 .Ft int
  98 .Fn pthread_attr_getstackaddr "const pthread_attr_t * restrict attr" "void ** restrict stackaddr"
  99 .Ft int
 100 .Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
 101 .Ft int
 102 .Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
 103 .Ft int
 104 .Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
 105 .Ft int
 106 .Fn pthread_attr_getinheritsched "const pthread_attr_t * restrict attr" "int * restrict inheritsched"
 107 .Ft int
 108 .Fn pthread_attr_setschedparam "pthread_attr_t * restrict attr" "const struct sched_param * restrict param"
 109 .Ft int
 110 .Fn pthread_attr_getschedparam "const pthread_attr_t * restrict attr" "struct sched_param * restrict param"
 111 .Ft int
 112 .Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
 113 .Ft int
 114 .Fn pthread_attr_getschedpolicy "const pthread_attr_t * restrict attr" "int * restrict policy"
 115 .Ft int
 116 .Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
 117 .Ft int
 118 .Fn pthread_attr_getscope "const pthread_attr_t * restrict attr" "int * restrict contentionscope"
 119 .Sh DESCRIPTION
 120 Thread attributes are used to specify parameters to
 121 .Fn pthread_create .
 122 One attribute object can be used in multiple calls to
 123 .Fn pthread_create ,
 124 with or without modifications between calls.
 125 .Pp
 126 The
 127 .Fn pthread_attr_init
 128 function initializes
 129 .Fa attr
 130 with all the default thread attributes.
 131 .Pp
 132 The
 133 .Fn pthread_attr_destroy
 134 function destroys
 135 .Fa attr .
 136 .Pp
 137 The
 138 .Fn pthread_attr_set*
 139 functions set the attribute that corresponds to each function name.
 140 .Pp
 141 The
 142 .Fn pthread_attr_get*
 143 functions copy the value of the attribute that corresponds to each function name
 144 to the location pointed to by the second function parameter.
 145 .Pp
 146 The attribute parameters for the
 147 .Fn pthread_attr_setdetachstate
 148 and
 149 .Fn pthread_attr_getdetachstate
 150 are mutually exclusive and must be one of:
 151 .Bl -tag -width xxxxxxxx
 152 .It Dv PTHREAD_CREATE_JOINABLE
 153 The threads must explicitly be waited for using the
 154 .Fn pthread_join
 155 function once they exit for their status to be received and their resources
 156 to be freed.
 157 This is the default.
 158 .It Dv PTHREAD_CREATE_DETACHED
 159 The thread's resources will automatically be freed once the thread exits,
 160 and the thread will not be joined.
 161 .El
 162 .Sh RETURN VALUES
 163 If successful, these functions return 0.
 164 Otherwise, an error number is returned to indicate the error.
 165 .Sh ERRORS
 166 .Fn pthread_attr_init
 167 should fail if:
 168 .Bl -tag -width Er
 169 .It Bq Er ENOMEM
 170 Out of memory.
 171 .El
 172 .Pp
 173 .Fn pthread_attr_destroy
 174 may fail if:
 175 .Bl -tag -width Er
 176 .It Bq Er EINVAL
 177 The value specified by
 178 .Fa attr
 179 is invalid.
 180 .El
 181 .Pp
 182 .Fn pthread_attr_setstacksize
 183 may fail if:
 184 .Bl -tag -width Er
 185 .It Bq Er EINVAL
 186 .Fa stacksize
 187 is less than
 188 .Dv PTHREAD_STACK_MIN .
 189 .El
 190 .Pp
 191 .Fn pthread_attr_setdetachstate
 192 should fail if:
 193 .Bl -tag -width Er
 194 .It Bq Er EINVAL
 195 The value specified by
 196 .Fa detachstate
 197 is invalid.
 198 .El
 199 .Pp
 200 Fn pthread_attr_setinheritsched
 201 may fail if:
 202 .Bl -tag -width Er
 203 .It Bq Er EINVAL
 204 Invalid value for
 205 .Fa attr .
 206 .El
 207 .Pp
 208 .Fn pthread_attr_setschedparam
 209 may fail if:
 210 .Bl -tag -width Er
 211 .It Bq Er EINVAL
 212 The value specified by
 213 .Fa attr
 214 is invalid.
 215 .It Bq Er ENOTSUP
 216 The value specified by
 217 .Fa param
 218 is invalid.
 219 .El
 220 .Pp
 221 .Fn pthread_attr_setschedpolicy
 222 may fail if:
 223 .Bl -tag -width Er
 224 .It Bq Er EINVAL
 225 Invalid value for
 226 .Fa attr .
 227 .It Bq Er ENOTSUP
 228 Invalid or unsupported value for
 229 .Fa policy .
 230 .El
 231 .Pp
 232 .Fn pthread_attr_setscope
 233 may fail if:
 234 .Bl -tag -width Er
 235 .It Bq Er EINVAL
 236 Invalid value for
 237 .Fa attr .
 238 .It Bq Er ENOTSUP
 239 Invalid or unsupported value for
 240 .Fa contentionscope .
 241 .El
 242 .Sh SEE ALSO
 243 .Xr pthread_create 3 ,
 244 .Xr pthread_join 3
 245 .Sh STANDARDS
 246 .Fn pthread_attr_init ,
 247 .Fn pthread_attr_destroy ,
 248 .Fn pthread_attr_setstacksize ,
 249 .Fn pthread_attr_getstacksize ,
 250 .Fn pthread_attr_setstackaddr ,
 251 .Fn pthread_attr_getstackaddr ,
 252 .Fn pthread_attr_setdetachstate ,
 253 .Fn pthread_attr_getdetachstate ,
 254 .Fn pthread_attr_setinheritsched ,
 255 .Fn pthread_attr_getinheritsched ,
 256 .Fn pthread_attr_setschedparam ,
 257 .Fn pthread_attr_setschedparam ,
 258 and
 259 .Fn pthread_attr_getschedparam
 260 .Fn pthread_attr_setschedpolicy ,
 261 .Fn pthread_attr_getschedpolicy ,
 262 .Fn pthread_attr_setscope ,
 263 and
 264 .Fn pthread_attr_getscope
 265 conform to
 266 .St -p1003.1-96 .