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 .Sh DESCRIPTION
  85 Mutex attributes are used to specify parameters to
  86 .Fn pthread_mutex_init .
  87 Like with thread attributes,
  88 one attribute object can be used in multiple calls to
  89 .Xr pthread_mutex_init 3 ,
  90 with or without modifications between calls.
  91 .Pp
  92 The
  93 .Fn pthread_mutexattr_init
  94 function initializes
  95 .Fa attr
  96 with all the default mutex attributes.
  97 .Pp
  98 The
  99 .Fn pthread_mutexattr_destroy
 100 function destroys
 101 .Fa attr .
 102 .Pp
 103 The
 104 .Fn pthread_mutexattr_settype
 105 functions set the mutex
 106 .Fa type
 107 value of the attribute.
 108 Valid mutex types are:
 109 .Bl -tag -width "XXX" -offset 2n
 110 .It Dv PTHREAD_MUTEX_NORMAL
 111 This type of mutex does not check for usage errors.
 112 It will deadlock if reentered, and result in undefined behavior if a
 113 locked mutex is unlocked by another thread.
 114 Attempts to unlock an already unlocked
 115 .Dv PTHREAD_MUTEX_NORMAL
 116 mutex will result in undefined behavior.
 117 .It Dv PTHREAD_MUTEX_ERRORCHECK
 118 These mutexes do check for usage errors.
 119 If an attempt is made to relock a
 120 .Dv PTHREAD_MUTEX_ERRORCHECK
 121 mutex without first dropping the lock, an error will be returned.
 122 If a thread attempts to unlock a
 123 .Dv PTHREAD_MUTEX_ERRORCHECK
 124 mutex that is locked by another thread, an error will be returned.
 125 If a thread attempts to unlock a
 126 .Dv PTHREAD_MUTEX_ERRORCHECK
 127 thread that is unlocked, an error will be returned.
 128 .It Dv PTHREAD_MUTEX_RECURSIVE
 129 These mutexes allow recursive locking.
 130 An attempt to relock a
 131 .Dv PTHREAD_MUTEX_RECURSIVE
 132 mutex that is already locked by the same thread succeeds.
 133 An equivalent number of
 134 .Xr pthread_mutex_unlock 3
 135 calls are needed before the mutex will wake another thread waiting
 136 on this lock.
 137 If a thread attempts to unlock a
 138 .Dv PTHREAD_MUTEX_RECURSIVE
 139 mutex that is locked by another thread, an error will be returned.
 140 If a thread attempts to unlock a
 141 .Dv PTHREAD_MUTEX_RECURSIVE
 142 thread that is unlocked, an error will be returned.
 143 .Pp
 144 It is advised that
 145 .Dv PTHREAD_MUTEX_RECURSIVE
 146 mutexes are not used with condition variables.
 147 This is because of the implicit unlocking done by
 148 .Xr pthread_cond_wait 3
 149 and
 150 .Xr pthread_cond_timedwait 3 .
 151 .It Dv PTHREAD_MUTEX_DEFAULT
 152 Also this type of mutex will cause undefined behavior if reentered.
 153 Unlocking a
 154 .Dv PTHREAD_MUTEX_DEFAULT
 155 mutex locked by another thread will result in undefined behavior.
 156 Attempts to unlock an already unlocked
 157 .Dv PTHREAD_MUTEX_DEFAULT
 158 mutex will result in undefined behavior.
 159 This is the default mutex type for
 160 .Fn pthread_mutexaddr_init .
 161 .El
 162 .Pp
 163 .Fn pthread_mutexattr_gettype
 164 functions copy the type value of the attribute to the location pointed to by the second parameter.
 165 .Pp
 166 The
 167 .Fn pthread_mutexattr_set*
 168 functions set the attribute that corresponds to each function name.
 169 .Pp
 170 The
 171 .Fn pthread_mutexattr_get*
 172 functions copy the value of the attribute that corresponds to each function name
 173 to the location pointed to by the second function parameter.
 174 .Sh RETURN VALUES
 175 If successful, these functions return 0.
 176 Otherwise, an error number is returned to indicate the error.
 177 .Sh ERRORS
 178 The
 179 .Fn pthread_mutexattr_init
 180 function shall fail if:
 181 .Bl -tag -width Er
 182 .It Bq Er ENOMEM
 183 Out of memory.
 184 .El
 185 .Pp
 186 The
 187 .Fn pthread_mutexattr_destroy
 188 function will fail if:
 189 .Bl -tag -width Er
 190 .It Bq Er EINVAL
 191 Invalid value for
 192 .Fa attr .
 193 .El
 194 .Pp
 195 The
 196 .Fn pthread_mutexattr_setprioceiling
 197 function will fail if:
 198 .Bl -tag -width Er
 199 .It Bq Er EINVAL
 200 Invalid value for
 201 .Fa attr ,
 202 or invalid value for
 203 .Fa prioceiling .
 204 .El
 205 .Pp
 206 The
 207 .Fn pthread_mutexattr_getprioceiling
 208 function will fail if:
 209 .Bl -tag -width Er
 210 .It Bq Er EINVAL
 211 Invalid value for
 212 .Fa attr .
 213 .El
 214 .Pp
 215 The
 216 .Fn pthread_mutexattr_setprotocol
 217 function will fail if:
 218 .Bl -tag -width Er
 219 .It Bq Er EINVAL
 220 Invalid value for
 221 .Fa attr ,
 222 or invalid value for
 223 .Fa protocol .
 224 .El
 225 .Pp
 226 The
 227 .Fn pthread_mutexattr_getprotocol
 228 function will fail if:
 229 .Bl -tag -width Er
 230 .It Bq Er EINVAL
 231 Invalid value for
 232 .Fa attr .
 233 .El
 234 .Pp
 235 The
 236 .Fn pthread_mutexattr_settype
 237 function shall fail if:
 238 .Bl -tag -width Er
 239 .It Bq Er EINVAL
 240 The value specified either by
 241 .Fa type
 242 or
 243 .Fa attr
 244 is invalid.
 245 .El
 246 .Pp
 247 The
 248 .Fn pthread_mutexattr_gettype
 249 function will fail if:
 250 .Bl -tag -width Er
 251 .It Bq Er EINVAL
 252 Invalid value for
 253 .Fa attr .
 254 .El
 255 .Sh SEE ALSO
 256 .Xr pthread_mutex_init 3
 257 .Sh STANDARDS
 258 The
 259 .Fn pthread_mutexattr_init
 260 and
 261 .Fn pthread_mutexattr_destroy
 262 functions conform to
 263 .St -p1003.1-96
 264 .Pp
 265 The
 266 .Fn pthread_mutexattr_setprioceiling ,
 267 .Fn pthread_mutexattr_getprioceiling ,
 268 .Fn pthread_mutexattr_setprotocol ,
 269 .Fn pthread_mutexattr_getprotocol ,
 270 .Fn pthread_mutexattr_settype ,
 271 and
 272 .Fn pthread_mutexattr_gettype
 273 functions conform to
 274 .St -susv2