share/man/man3/pthread_mutexattr.3

   1 .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
   2 .\" Copyright (c) 2021 The FreeBSD Foundation, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Part of this documentation was written by
   6 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
   7 .\" from the FreeBSD Foundation.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice(s), this list of conditions and the following disclaimer as
  14 .\"    the first lines of this file unmodified other than the possible
  15 .\"    addition of one or more copyright notices.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice(s), this list of conditions and the following disclaimer in
  18 .\"    the documentation and/or other materials provided with the
  19 .\"    distribution.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  22 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  24 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  25 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  26 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  27 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  28 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  29 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  30 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  31 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .Dd October 27, 2023
  33 .Dt PTHREAD_MUTEXATTR 3
  34 .Os
  35 .Sh NAME
  36 .Nm pthread_mutexattr_init ,
  37 .Nm pthread_mutexattr_destroy ,
  38 .Nm pthread_mutexattr_setprioceiling ,
  39 .Nm pthread_mutexattr_getprioceiling ,
  40 .Nm pthread_mutexattr_setprotocol ,
  41 .Nm pthread_mutexattr_getprotocol ,
  42 .Nm pthread_mutexattr_setpshared ,
  43 .Nm pthread_mutexattr_getpshared ,
  44 .Nm pthread_mutexattr_setrobust ,
  45 .Nm pthread_mutexattr_getrobust ,
  46 .Nm pthread_mutexattr_settype ,
  47 .Nm pthread_mutexattr_gettype
  48 .Nd mutex attribute operations
  49 .Sh LIBRARY
  50 .Lb libpthread
  51 .Sh SYNOPSIS
  52 .In pthread.h
  53 .Ft int
  54 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
  55 .Ft int
  56 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
  57 .Ft int
  58 .Fo pthread_mutexattr_setprioceiling
  59 .Fa "pthread_mutexattr_t *attr" "int prioceiling"
  60 .Fc
  61 .Ft int
  62 .Fo pthread_mutexattr_getprioceiling
  63 .Fa "const pthread_mutexattr_t *attr" "int *prioceiling"
  64 .Fc
  65 .Ft int
  66 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
  67 .Ft int
  68 .Fo pthread_mutexattr_getprotocol
  69 .Fa "const pthread_mutexattr_t *restrict attr" "int *restrict protocol"
  70 .Fc
  71 .Ft int
  72 .Fo pthread_mutexattr_setpshared
  73 .Fa "pthread_mutexattr_t *attr" "int shared"
  74 .Fc
  75 .Ft int
  76 .Fo pthread_mutexattr_getpshared
  77 .Fa "const pthread_mutexattr_t *attr" "int *shared"
  78 .Fc
  79 .Ft int
  80 .Fn pthread_mutexattr_setrobust "pthread_mutexattr_t *attr" "int robust"
  81 .Ft int
  82 .Fn pthread_mutexattr_getrobust "pthread_mutexattr_t *attr" "int *robust"
  83 .Ft int
  84 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
  85 .Ft int
  86 .Fo pthread_mutexattr_gettype
  87 .Fa "const pthread_mutexattr_t *restrict attr" "int *restrict type"
  88 .Fc
  89 .Sh DESCRIPTION
  90 Mutex attributes are used to specify parameters to
  91 .Fn pthread_mutex_init .
  92 One attribute object can be used in multiple calls to
  93 .Fn pthread_mutex_init ,
  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_setprioceiling
 109 function sets the priority ceiling for the mutex, used
 110 by threads executed under the
 111 .Dv PTHREAD_PRIO_PROTECT
 112 protocol.
 113 .Pp
 114 The
 115 .Fn pthread_mutexattr_setprotocol
 116 function specifies the protocol to be followed in utilizing mutexes.
 117 The
 118 .Fa protocol
 119 argument can take one of the following values:
 120 .Bl -tag -width PTHREAD_PRIO_PROTECT
 121 .It PTHREAD_PRIO_NONE
 122 Priority and scheduling of the thread owning this mutex is not
 123 affected by its mutex ownership.
 124 .It PTHREAD_PRIO_INHERIT
 125 Request priority-inheritance protocol, where the thread owning the mutex
 126 is executed at the highest priority among priorities of all threads waiting
 127 on any mutex owned by this thread.
 128 .It PTHREAD_PRIO_PROTECT
 129 Request priority-inheritance protocol, where the thread owning the mutex
 130 is executed at highest priority among priorities or priority ceilings of
 131 all threads waiting on any mutex owned by this thread.
 132 .El
 133 .Pp
 134 The
 135 .Fn pthread_mutexattr_setpshared
 136 function sets the process-shared attribute of
 137 .Fa attr
 138 to the value specified in
 139 .Fa pshared .
 140 The argument
 141 .Fa pshared
 142 may have one of the following values:
 143 .Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE"
 144 .It Dv PTHREAD_PROCESS_PRIVATE
 145 The mutex may only be used by threads in the same process as the one
 146 that created the object.
 147 .It Dv PTHREAD_PROCESS_SHARED
 148 The mutex may be used by
 149 threads in processes other than the one that created the object,
 150 assuming other processes share access to the memory where the mutex
 151 was allocated.
 152 .El
 153 See
 154 .Xr libthr 3
 155 for details of the implementation of the shared mutexes,
 156 and their limitations.
 157 .Pp
 158 The
 159 .Fn pthread_mutexattr_setrobust
 160 function specifies robustness attribute of the mutex.
 161 Possible values for the
 162 .Fa robust
 163 argument are
 164 .Bl -tag -width PTHREAD_MUTEX_STALLED
 165 .It PTHREAD_MUTEX_STALLED
 166 No special actions are taken if the thread owning the mutex is terminated
 167 without unlocking the mutex lock.
 168 This can lead to deadlocks if no other thread can unlock the mutex.
 169 This is the default value.
 170 .It PTHREAD_MUTEX_ROBUST
 171 If the process containing the owning thread of a robust mutex, or owning
 172 thread, terminates while holding the mutex lock, the next thread that
 173 acquires the mutex is notified about the termination
 174 by the return value
 175 .Ev EOWNERDEAD
 176 from the locking function.
 177 Then, either
 178 .Xr pthread_mutex_consistent 3
 179 can be used to repair the mutex lock state, or
 180 .Xr pthread_mutex_unlock 3
 181 can unlock the mutex lock but also put it an unusable state,
 182 where all further attempts to acquire it result in the
 183 .Ev ENOTRECOVERABLE
 184 error.
 185 .El
 186 .Pp
 187 The
 188 .Fn pthread_mutexattr_settype
 189 function sets the type of the mutex.
 190 The type affects the behavior of calls which lock and unlock the mutex.
 191 The possible values for the
 192 .Fa type
 193 argument are
 194 .Bl -tag -width PTHREAD_MUTEX_ERRORCHECK
 195 .It PTHREAD_MUTEX_NORMAL
 196 Both recursive locking, and unlocking when the lock is not owned by the current
 197 thread, cause an error to be returned from the corresponding functions.
 198 This matches
 199 .Dv PTHREAD_MUTEX_ERRORCHECK
 200 but somewhat contradicts the behavior mandated by POSIX.
 201 .It PTHREAD_MUTEX_ERRORCHECK
 202 Both recursive locking, and unlocking when the lock is not owned by the current
 203 thread, cause an error returned from the corresponding functions.
 204 .It PTHREAD_MUTEX_RECURSIVE
 205 Recursive locking is allowed.
 206 Attempt to unlock when current thread is not an owner of the lock causes
 207 an error to be returned.
 208 .It PTHREAD_MUTEX_DEFAULT
 209 The
 210 .Fx
 211 implementation maps this type to
 212 .Dv PTHREAD_MUTEX_ERRORCHECK
 213 type.
 214 .El
 215 .Pp
 216 The
 217 .Fn pthread_mutexattr_get*
 218 functions copy the value of the attribute that corresponds to each function name
 219 to the location pointed to by the second function parameter.
 220 .Sh RETURN VALUES
 221 If successful, these functions return 0.
 222 Otherwise, an error number is returned to indicate the error.
 223 .Sh ERRORS
 224 The
 225 .Fn pthread_mutexattr_init
 226 function will fail if:
 227 .Bl -tag -width Er
 228 .It Bq Er ENOMEM
 229 Out of memory.
 230 .El
 231 .Pp
 232 The
 233 .Fn pthread_mutexattr_destroy
 234 function will fail if:
 235 .Bl -tag -width Er
 236 .It Bq Er EINVAL
 237 Invalid value for
 238 .Fa attr .
 239 .El
 240 .Pp
 241 The
 242 .Fn pthread_mutexattr_setprioceiling
 243 function will fail if:
 244 .Bl -tag -width Er
 245 .It Bq Er EINVAL
 246 Invalid value for
 247 .Fa attr ,
 248 or invalid value for
 249 .Fa prioceiling .
 250 .El
 251 .Pp
 252 The
 253 .Fn pthread_mutexattr_getprioceiling
 254 function will fail if:
 255 .Bl -tag -width Er
 256 .It Bq Er EINVAL
 257 Invalid value for
 258 .Fa attr .
 259 .El
 260 .Pp
 261 The
 262 .Fn pthread_mutexattr_setprotocol
 263 function will fail if:
 264 .Bl -tag -width Er
 265 .It Bq Er EINVAL
 266 Invalid value for
 267 .Fa attr ,
 268 or invalid value for
 269 .Fa protocol .
 270 .El
 271 .Pp
 272 The
 273 .Fn pthread_mutexattr_getprotocol
 274 function will fail if:
 275 .Bl -tag -width Er
 276 .It Bq Er EINVAL
 277 Invalid value for
 278 .Fa attr .
 279 .El
 280 .Pp
 281 The
 282 .Fn pthread_mutexattr_setpshared
 283 function will fail if:
 284 .Bl -tag -width Er
 285 .It Bq Er EINVAL
 286 Invalid value for
 287 .Fa attr ,
 288 or invalid value for
 289 .Fa shared .
 290 .El
 291 .Pp
 292 The
 293 .Fn pthread_mutexattr_getpshared
 294 function will fail if:
 295 .Bl -tag -width Er
 296 .It Bq Er EINVAL
 297 Invalid value for
 298 .Fa attr .
 299 .El
 300 .Pp
 301 The
 302 .Fn pthread_mutexattr_settype
 303 function will fail if:
 304 .Bl -tag -width Er
 305 .It Bq Er EINVAL
 306 Invalid value for
 307 .Fa attr ,
 308 or invalid value for
 309 .Fa type .
 310 .El
 311 .Pp
 312 The
 313 .Fn pthread_mutexattr_gettype
 314 function will fail if:
 315 .Bl -tag -width Er
 316 .It Bq Er EINVAL
 317 Invalid value for
 318 .Fa attr .
 319 .El
 320 .Pp
 321 The
 322 .Fn pthread_mutexattr_setrobust
 323 function will fail if:
 324 .Bl -tag -width Er
 325 .It Bq Er EINVAL
 326 Invalid value for
 327 .Fa attr ,
 328 or invalid value for
 329 .Fa robust .
 330 .El
 331 .Pp
 332 The
 333 .Fn pthread_mutexattr_getrobust
 334 function will fail if:
 335 .Bl -tag -width Er
 336 .It Bq Er EINVAL
 337 Invalid value for
 338 .Fa attr .
 339 .El
 340 .Sh SEE ALSO
 341 .Xr libthr 3 ,
 342 .Xr pthread_mutex_init 3
 343 .Sh STANDARDS
 344 The
 345 .Fn pthread_mutexattr_init
 346 and
 347 .Fn pthread_mutexattr_destroy
 348 functions conform to
 349 .St -p1003.1-96
 350 .Pp
 351 The
 352 .Fn pthread_mutexattr_setprioceiling ,
 353 .Fn pthread_mutexattr_getprioceiling ,
 354 .Fn pthread_mutexattr_setprotocol ,
 355 .Fn pthread_mutexattr_getprotocol ,
 356 .Fn pthread_mutexattr_setpshared ,
 357 .Fn pthread_mutexattr_getpshared ,
 358 .Fn pthread_mutexattr_settype ,
 359 and
 360 .Fn pthread_mutexattr_gettype
 361 functions conform to
 362 .St -susv2 .
 363 The
 364 .Fn pthread_mutexattr_setrobust
 365 and
 366 .Fn pthread_mutexattr_getrobust
 367 functions conform to
 368 .St -susv4 .