man/pthread_mutexattr.3

   1 .\" $NetBSD: pthread_mutexattr.3,v 1.11 2010/07/08 22:46:34 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 2002, 2010 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$
  53 .Dd July 9, 2010
  54 .Dt PTHREAD_MUTEXATTR 3
  55 .Os
  56 .Sh NAME
  57 .Nm pthread_mutexattr_init ,
  58 .Nm pthread_mutexattr_destroy ,
  59 .Nm pthread_mutexattr_setprioceiling ,
  60 .Nm pthread_mutexattr_getprioceiling ,
  61 .Nm pthread_mutexattr_setprotocol ,
  62 .Nm pthread_mutexattr_getprotocol ,
  63 .Nm pthread_mutexattr_settype ,
  64 .Nm pthread_mutexattr_gettype
  65 .Nd mutex attribute operations
  66 .Sh SYNOPSIS
  67 .In pthread.h
  68 .Ft int
  69 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
  70 .Ft int
  71 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
  72 .Ft int
  73 .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"
  74 .Ft int
  75 .Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *prioceiling"
  76 .Ft int
  77 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
  78 .Ft int
  79 .Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
  80 .Ft int
  81 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
  82 .Ft int
  83 .Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
  84 .Ft int
  85 .Fn pthread_mutexattr_setpolicy_np "pthread_mutexattr_t *attr" "int policy"
  86 .Ft int
  87 .Fn pthread_mutexattr_getpolicy_np "pthread_mutexattr_t *attr" "int *policy"
  88 .Sh DESCRIPTION
  89 Mutex attributes are used to specify parameters to
  90 .Fn pthread_mutex_init .
  91 Like with thread attributes,
  92 one attribute object can be used in multiple calls to
  93 .Xr pthread_mutex_init 3 ,
  94 with or without modifications between calls.
  95 .Pp
  96 The
  97 .Fn pthread_mutexattr_init
  98 function initializes
  99 .Fa attr
 100 with all the default mutex attributes.
 101 .Pp
 102 The
 103 .Fn pthread_mutexattr_destroy
 104 function destroys
 105 .Fa attr .
 106 .Pp
 107 The
 108 .Fn pthread_mutexattr_settype
 109 functions set the mutex
 110 .Fa type
 111 value of the attribute.
 112 Valid mutex types are:
 113 .Bl -tag -width "XXX" -offset 2n
 114 .It Dv PTHREAD_MUTEX_NORMAL
 115 This type of mutex does not check for usage errors.
 116 It will deadlock if reentered, and result in undefined behavior if a
 117 locked mutex is unlocked by another thread.
 118 Attempts to unlock an already unlocked
 119 .Dv PTHREAD_MUTEX_NORMAL
 120 mutex will result in undefined behavior.
 121 .It Dv PTHREAD_MUTEX_ERRORCHECK
 122 These mutexes do check for usage errors.
 123 If an attempt is made to relock a
 124 .Dv PTHREAD_MUTEX_ERRORCHECK
 125 mutex without first dropping the lock, an error will be returned.
 126 If a thread attempts to unlock a
 127 .Dv PTHREAD_MUTEX_ERRORCHECK
 128 mutex that is locked by another thread, an error will be returned.
 129 If a thread attempts to unlock a
 130 .Dv PTHREAD_MUTEX_ERRORCHECK
 131 thread that is unlocked, an error will be returned.
 132 .It Dv PTHREAD_MUTEX_RECURSIVE
 133 These mutexes allow recursive locking.
 134 An attempt to relock a
 135 .Dv PTHREAD_MUTEX_RECURSIVE
 136 mutex that is already locked by the same thread succeeds.
 137 An equivalent number of
 138 .Xr pthread_mutex_unlock 3
 139 calls are needed before the mutex will wake another thread waiting
 140 on this lock.
 141 If a thread attempts to unlock a
 142 .Dv PTHREAD_MUTEX_RECURSIVE
 143 mutex that is locked by another thread, an error will be returned.
 144 If a thread attempts to unlock a
 145 .Dv PTHREAD_MUTEX_RECURSIVE
 146 thread that is unlocked, an error will be returned.
 147 .Pp
 148 It is advised that
 149 .Dv PTHREAD_MUTEX_RECURSIVE
 150 mutexes are not used with condition variables.
 151 This is because of the implicit unlocking done by
 152 .Xr pthread_cond_wait 3
 153 and
 154 .Xr pthread_cond_timedwait 3 .
 155 .It Dv PTHREAD_MUTEX_DEFAULT
 156 Also this type of mutex will cause undefined behavior if reentered.
 157 Unlocking a
 158 .Dv PTHREAD_MUTEX_DEFAULT
 159 mutex locked by another thread will result in undefined behavior.
 160 Attempts to unlock an already unlocked
 161 .Dv PTHREAD_MUTEX_DEFAULT
 162 mutex will result in undefined behavior.
 163 This is the default mutex type for
 164 .Fn pthread_mutexaddr_init .
 165 .El
 166 .Pp
 167 .Fn pthread_mutexattr_gettype
 168 functions copy the type value of the attribute to the location pointed to by the second parameter.
 169 .Pp
 170 The
 171 .Fn pthread_mutexattr_setpolicy_np
 172 function sets the mutex
 173 .Fa policy
 174 value of the attribute.
 175 Valid mutex policies are:
 176 .Bl -tag -width "XXX" -offset 2n
 177 .It Dv PTHREAD_MUTEX_POLICY_FIRSTFIT_NP
 178 The first-fit mutex policy allows acquisition of the mutex to occur in any
 179 order. This policy is similar in operation to os_unfair_lock, new contending
 180 acquirers may obtain ownership of the mutex ahead of existing waiters.
 181 .It Dv PTHREAD_MUTEX_POLICY_FAIRSHARE_NP
 182 The fairshare mutex policy guarantees that ownership of a contended mutex will
 183 be granted to waiters on a strictly ordered first-in, first-out basis. That is,
 184 a mutex holder that unlocks the mutex and then attempts to relock will wait
 185 behind existing threads already waiting on the mutex before being granted
 186 ownership again.
 187 .El
 188 .Pp
 189 The
 190 .Fn pthread_mutexattr_getpolicy_np
 191 function copies the mutex
 192 .Fa policy
 193 value of the attribute to the location pointed to by the second parameter.
 194 .Pp
 195 The
 196 .Fn pthread_mutexattr_set*
 197 functions set the attribute that corresponds to each function name.
 198 .Pp
 199 The
 200 .Fn pthread_mutexattr_get*
 201 functions copy the value of the attribute that corresponds to each function name
 202 to the location pointed to by the second function parameter.
 203 .Sh RETURN VALUES
 204 If successful, these functions return 0.
 205 Otherwise, an error number is returned to indicate the error.
 206 .Sh ENVIRONMENT
 207 The following environment variables change the behavior of the pthread mutex
 208 implementation.
 209 .Bl -tag -width "XXX" -offset 2n
 210 .It Ev PTHREAD_MUTEX_DEFAULT_POLICY
 211 Controls the process-wide policy used when initializing a pthread_mutex_t that
 212 has not had a policy set via
 213 .Fn pthread_mutexattr_setpolicy_np .
 214 The valid values are mapped as:
 215 .Pp
 216 .Bl -tag -width "XXX"
 217 .It Fa 1
 218 .Dv PTHREAD_MUTEX_POLICY_FAIRSHARE_NP
 219 .It Fa 3
 220 .Dv PTHREAD_MUTEX_POLICY_FIRSTFIT_NP
 221 .El
 222 .El
 223 .Sh BACKWARDS COMPATIBILITY
 224 Prior to macOS 10.14 (iOS and tvOS 12.0, watchOS 5.0) the only available
 225 pthread mutex policy mode was
 226 .Dv PTHREAD_MUTEX_POLICY_FAIRSHARE_NP .
 227 macOS 10.14 (iOS and tvOS 12.0, watchOS 5.0) introduces
 228 .Dv PTHREAD_MUTEX_POLICY_FIRSTFIT_NP
 229 and also makes this the default mode for mutexes initialized without a policy
 230 attribute set.
 231 .Pp
 232 Attempting to use
 233 .Fn pthread_mutexattr_setpolicy_np
 234 to set the policy of a pthread_mutex_t to
 235 .Dv PTHREAD_MUTEX_POLICY_FIRSTFIT_NP
 236 on earlier releases will fail with
 237 .Er EINVAL
 238 and the mutex will continue to operate in fairshare mode.
 239 .Sh ERRORS
 240 The
 241 .Fn pthread_mutexattr_init
 242 function shall fail if:
 243 .Bl -tag -width Er
 244 .It Bq Er ENOMEM
 245 Out of memory.
 246 .El
 247 .Pp
 248 The
 249 .Fn pthread_mutexattr_destroy
 250 function will fail if:
 251 .Bl -tag -width Er
 252 .It Bq Er EINVAL
 253 Invalid value for
 254 .Fa attr .
 255 .El
 256 .Pp
 257 The
 258 .Fn pthread_mutexattr_setprioceiling
 259 function will fail if:
 260 .Bl -tag -width Er
 261 .It Bq Er EINVAL
 262 Invalid value for
 263 .Fa attr ,
 264 or invalid value for
 265 .Fa prioceiling .
 266 .El
 267 .Pp
 268 The
 269 .Fn pthread_mutexattr_getprioceiling
 270 function will fail if:
 271 .Bl -tag -width Er
 272 .It Bq Er EINVAL
 273 Invalid value for
 274 .Fa attr .
 275 .El
 276 .Pp
 277 The
 278 .Fn pthread_mutexattr_setprotocol
 279 function will fail if:
 280 .Bl -tag -width Er
 281 .It Bq Er EINVAL
 282 Invalid value for
 283 .Fa attr ,
 284 or invalid value for
 285 .Fa protocol .
 286 .El
 287 .Pp
 288 The
 289 .Fn pthread_mutexattr_getprotocol
 290 function will fail if:
 291 .Bl -tag -width Er
 292 .It Bq Er EINVAL
 293 Invalid value for
 294 .Fa attr .
 295 .El
 296 .Pp
 297 The
 298 .Fn pthread_mutexattr_settype
 299 function shall fail if:
 300 .Bl -tag -width Er
 301 .It Bq Er EINVAL
 302 The value specified either by
 303 .Fa type
 304 or
 305 .Fa attr
 306 is invalid.
 307 .El
 308 .Pp
 309 The
 310 .Fn pthread_mutexattr_gettype
 311 function will fail if:
 312 .Bl -tag -width Er
 313 .It Bq Er EINVAL
 314 Invalid value for
 315 .Fa attr .
 316 .El
 317 .Pp
 318 The
 319 .Fn pthread_mutexattr_setpolicy_np
 320 function will fail if:
 321 .Bl -tag -width Er
 322 .It Bq Er EINVAL
 323 Invalid value for
 324 .Fa attr .
 325 .El
 326 .Pp
 327 The
 328 .Fn pthread_mutexattr_getpolicy_np
 329 function will fail if:
 330 .Bl -tag -width Er
 331 .It Bq Er EINVAL
 332 The value specified either by
 333 .Fa type
 334 or
 335 .Fa attr
 336 is invalid.
 337 .El
 338 .Sh SEE ALSO
 339 .Xr pthread_mutex_init 3
 340 .Sh STANDARDS
 341 The
 342 .Fn pthread_mutexattr_init
 343 and
 344 .Fn pthread_mutexattr_destroy
 345 functions conform to
 346 .St -p1003.1-96
 347 .Pp
 348 The
 349 .Fn pthread_mutexattr_setprioceiling ,
 350 .Fn pthread_mutexattr_getprioceiling ,
 351 .Fn pthread_mutexattr_setprotocol ,
 352 .Fn pthread_mutexattr_getprotocol ,
 353 .Fn pthread_mutexattr_settype ,
 354 and
 355 .Fn pthread_mutexattr_gettype
 356 functions conform to
 357 .St -susv2