pthreads/pthread_mutexattr.3

   1 .\" $NetBSD: pthread_mutexattr.3,v 1.3 2003/07/04 08:36:06 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2002 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 .\" 3. Neither the name of The NetBSD Foundation nor the names of its
  14 .\"    contributors may be used to endorse or promote products derived
  15 .\"    from this software without specific prior written permission.
  16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  17 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  18 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26 .\" POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
  29 .\" All rights reserved.
  30 .\"
  31 .\" Redistribution and use in source and binary forms, with or without
  32 .\" modification, are permitted provided that the following conditions
  33 .\" are met:
  34 .\" 1. Redistributions of source code must retain the above copyright
  35 .\"    notice(s), this list of conditions and the following disclaimer as
  36 .\"    the first lines of this file unmodified other than the possible
  37 .\"    addition of one or more copyright notices.
  38 .\" 2. Redistributions in binary form must reproduce the above copyright
  39 .\"    notice(s), this list of conditions and the following disclaimer in
  40 .\"    the documentation and/or other materials provided with the
  41 .\"    distribution.
  42 .\"
  43 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  44 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  45 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  46 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  47 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  48 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  49 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  50 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  51 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  52 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  53 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  54 .\"
  55 .\" $FreeBSD: src/lib/libpthread/man/pthread_mutexattr.3,v 1.8 2002/09/16 19:29:29 mini Exp $
  56 .Dd January 30, 2003
  57 .Dt PTHREAD_MUTEXATTR 3
  58 .Os
  59 .Sh NAME
  60 .Nm pthread_mutexattr_destroy ,
  61 .Nm pthread_mutexattr_getprioceiling ,
  62 .Nm pthread_mutexattr_getprotocol ,
  63 .Nm pthread_mutexattr_gettype ,
  64 .Nm pthread_mutexattr_init ,
  65 .Nm pthread_mutexattr_setprioceiling ,
  66 .Nm pthread_mutexattr_setprotocol ,
  67 .Nm pthread_mutexattr_settype
  68 .Nd mutex attribute operations
  69 .Sh SYNOPSIS
  70 .Fd #include <pthread.h>
  71 .Ft int
  72 .Fo pthread_mutexattr_destroy
  73 .Fa "pthread_mutexattr_t *attr"
  74 .Fc
  75 .Ft int
  76 .Fo pthread_mutexattr_getprioceiling
  77 .Fa "const pthread_mutexattr_t *attr"
  78 .Fa "int *prioceiling"
  79 .Fc
  80 .\" To match the SUS, this should be:
  81 .\" .Ft int
  82 .\" .Fo pthread_mutexattr_getprioceiling
  83 .\" .Fa "pthread_mutexattr_t *restrict attr"
  84 .\" .Fa "int *restrict prioceiling"
  85 .\" .Fc
  86 .Ft int
  87 .Fo pthread_mutexattr_getprotocol
  88 .Fa "const pthread_mutexattr_t *attr"
  89 .Fa "int *protocol"
  90 .Fc
  91 .\" To match the SUS, this should be:
  92 .\" .Ft int
  93 .\" .Fo pthread_mutexattr_getprotocol
  94 .\" .Fa "pthread_mutexattr_t *restrict attr"
  95 .\" .Fa "int *restrict protocol"
  96 .\" .Fc
  97 .Ft int
  98 .Fo pthread_mutexattr_gettype
  99 .Fa "const pthread_mutexattr_t *attr"
 100 .Fa "int *type"
 101 .Fc
 102 .\" To match the SUS, this should be:
 103 .\" .Ft int
 104 .\" .Fo pthread_mutexattr_gettype
 105 .\" .Fa "pthread_mutexattr_t *restrict attr"
 106 .\" .Fa "int *restrict type"
 107 .\" .Fc
 108 .Ft int
 109 .Fo pthread_mutexattr_init
 110 .Fa "pthread_mutexattr_t *attr"
 111 .Fc
 112 .Ft int
 113 .Fo pthread_mutexattr_setprioceiling
 114 .Fa "pthread_mutexattr_t *attr"
 115 .Fa "int prioceiling"
 116 .Fc
 117 .Ft int
 118 .Fo pthread_mutexattr_setprotocol
 119 .Fa "pthread_mutexattr_t *attr"
 120 .Fa "int protocol"
 121 .Fc
 122 .Ft int
 123 .Fo pthread_mutexattr_settype
 124 .Fa "pthread_mutexattr_t *attr"
 125 .Fa "int type"
 126 .Fc
 127 .Sh DESCRIPTION
 128 Mutex attributes are used to specify parameters to
 129 .Fn pthread_mutex_init .
 130 One attribute object can be used in multiple calls to
 131 .Fn pthread_mutex_init ,
 132 with or without modifications between calls.
 133 .Pp
 134 The
 135 .Fn pthread_mutexattr_init
 136 function initializes
 137 .Fa attr
 138 with all of the default mutex attributes.
 139 .Pp
 140 The
 141 .Fn pthread_mutexattr_destroy
 142 function destroys
 143 .Fa attr .
 144 .Pp
 145 The
 146 .Fn pthread_mutexattr_settype
 147 function sets the mutex type value of the attribute.  Valid mutex types are:
 148 .Dv PTHREAD_MUTEX_NORMAL ,
 149 .Dv PTHREAD_MUTEX_ERRORCHECK ,
 150 .Dv PTHREAD_MUTEX_RECURSIVE ,
 151 and
 152 .Dv PTHREAD_MUTEX_DEFAULT .
 153 The default mutex type for
 154 .Fn pthread_mutexaddr_init
 155 is
 156 .Dv PTHREAD_MUTEX_DEFAULT .
 157 .Pp
 158 .Dv PTHREAD_MUTEX_NORMAL
 159 mutexes do not check for usage errors.
 160 .Dv PTHREAD_MUTEX_NORMAL
 161 mutexes will deadlock if reentered, and result in undefined behavior if a
 162 locked mutex is unlocked by another thread.  Attempts to unlock an already
 163 unlocked
 164 .Dv PTHREAD_MUTEX_NORMAL
 165 mutex will result in undefined behavior.
 166 .Pp
 167 .Dv PTHREAD_MUTEX_ERRORCHECK
 168 mutexes do check for usage errors.
 169 If an attempt is made to relock a
 170 .Dv PTHREAD_MUTEX_ERRORCHECK
 171 mutex without first dropping the lock, an error will be returned.
 172 If a thread attempts to unlock a
 173 .Dv PTHREAD_MUTEX_ERRORCHECK
 174 mutex that is locked by another thread, an error will be returned.  If a
 175 thread attempts to unlock a
 176 .Dv PTHREAD_MUTEX_ERRORCHECK
 177 thread that is unlocked, an error will be returned.
 178 .Pp
 179 .Dv PTHREAD_MUTEX_RECURSIVE
 180 mutexes allow recursive locking.
 181 An attempt to relock a
 182 .Dv PTHREAD_MUTEX_RECURSIVE
 183 mutex that is already locked by the same thread succeeds.  An equivalent
 184 number of
 185 .Xr pthread_mutex_unlock 3
 186 calls are needed before the mutex will wake another thread waiting on this
 187 lock.  If a thread attempts to unlock a
 188 .Dv PTHREAD_MUTEX_RECURSIVE
 189 mutex that is locked by another thread, an error will be returned.  If a thread attemps to unlock a
 190 .Dv PTHREAD_MUTEX_RECURSIVE
 191 thread that is unlocked, an error will be returned.
 192 .Pp
 193 .Dv PTHREAD_MUTEX_DEFAULT
 194 mutexes result in undefined behavior if reentered.
 195 Unlocking a
 196 .Dv PTHREAD_MUTEX_DEFAULT
 197 mutex locked by another thread will result in undefined behavior.  Attempts to unlock an already
 198 unlocked
 199 .Dv PTHREAD_MUTEX_DEFAULT
 200 mutex will result in undefined behavior.
 201 .Pp
 202 .Fn pthread_mutexattr_gettype
 203 functions copy the type value of the attribute to the location pointed to by the second parameter.
 204 .Pp
 205 The
 206 .Fn pthread_mutexattr_set*
 207 functions set the attribute that corresponds to each function name.
 208 .Pp
 209 The
 210 .Fn pthread_mutexattr_get*
 211 functions copy the value of the attribute that corresponds to each function name
 212 to the location pointed to by the second function parameter.
 213 .Sh RETURN VALUES
 214 If successful, these functions return 0.
 215 Otherwise, an error number is returned to indicate the error.
 216 .Sh ERRORS
 217 .Fn pthread_mutexattr_init
 218 will fail if:
 219 .Bl -tag -width Er
 220 .It Bq Er ENOMEM
 221 Out of memory.
 222 .El
 223 .Pp
 224 .Fn pthread_mutexattr_destroy
 225 will fail if:
 226 .Bl -tag -width Er
 227 .It Bq Er EINVAL
 228 Invalid value for
 229 .Fa attr .
 230 .El
 231 .Pp
 232 .Fn pthread_mutexattr_setprioceiling
 233 will fail if:
 234 .Bl -tag -width Er
 235 .It Bq Er EINVAL
 236 Invalid value for
 237 .Fa attr ,
 238 or invalid value for
 239 .Fa prioceiling .
 240 .El
 241 .Pp
 242 .Fn pthread_mutexattr_getprioceiling
 243 will fail if:
 244 .Bl -tag -width Er
 245 .It Bq Er EINVAL
 246 Invalid value for
 247 .Fa attr .
 248 .El
 249 .Pp
 250 .Fn pthread_mutexattr_setprotocol
 251 will fail if:
 252 .Bl -tag -width Er
 253 .It Bq Er EINVAL
 254 Invalid value for
 255 .Fa attr ,
 256 or invalid value for
 257 .Fa protocol .
 258 .El
 259 .Pp
 260 .Fn pthread_mutexattr_getprotocol
 261 will fail if:
 262 .Bl -tag -width Er
 263 .It Bq Er EINVAL
 264 Invalid value for
 265 .Fa attr .
 266 .El
 267 .Pp
 268 .Fn pthread_mutexattr_settype
 269 will fail if:
 270 .Bl -tag -width Er
 271 .It Bq Er EINVAL
 272 Invalid value for
 273 .Fa attr ,
 274 or invalid value for
 275 .Fa type .
 276 .El
 277 .Pp
 278 .Fn pthread_mutexattr_gettype
 279 will fail if:
 280 .Bl -tag -width Er
 281 .It Bq Er EINVAL
 282 Invalid value for
 283 .Fa attr .
 284 .El
 285 .Sh SEE ALSO
 286 .Xr pthread_mutex_init 3
 287 .Sh STANDARDS
 288 .Fn pthread_mutexattr_init
 289 and
 290 .Fn pthread_mutexattr_destroy
 291 conform to
 292 .St -p1003.1-96
 293 .Pp
 294 .Fn pthread_mutexattr_setprioceiling ,
 295 .Fn pthread_mutexattr_getprioceiling ,
 296 .Fn pthread_mutexattr_setprotocol ,
 297 .Fn pthread_mutexattr_getprotocol ,
 298 .Fn pthread_mutexattr_settype ,
 299 and
 300 .Fn pthread_mutexattr_gettype
 301 conform to
 302 .St -susv2