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_init ,
  61 .Nm pthread_mutexattr_destroy ,
  62 .Nm pthread_mutexattr_setprioceiling ,
  63 .Nm pthread_mutexattr_getprioceiling ,
  64 .Nm pthread_mutexattr_setprotocol ,
  65 .Nm pthread_mutexattr_getprotocol ,
  66 .Nm pthread_mutexattr_settype ,
  67 .Nm pthread_mutexattr_gettype
  68 .Nd mutex attribute operations
  69 .Sh SYNOPSIS
  70 .Fd #include <pthread.h>
  71 .Ft int
  72 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
  73 .Ft int
  74 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
  75 .Ft int
  76 .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"
  77 .Ft int
  78 .Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *prioceiling"
  79 .Ft int
  80 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
  81 .Ft int
  82 .Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
  83 .Ft int
  84 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
  85 .Ft int
  86 .Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
  87 .Sh DESCRIPTION
  88 Mutex attributes are used to specify parameters to
  89 .Fn pthread_mutex_init .
  90 One attribute object can be used in multiple calls to
  91 .Fn pthread_mutex_init ,
  92 with or without modifications between calls.
  93 .Pp
  94 The
  95 .Fn pthread_mutexattr_init
  96 function initializes
  97 .Fa attr
  98 with all the default mutex attributes.
  99 .Pp
 100 The
 101 .Fn pthread_mutexattr_destroy
 102 function destroys
 103 .Fa attr .
 104 .Pp
 105 The
 106 .Fn pthread_mutexattr_settype
 107 functions set the mutex type value of the attribute.  Valid mutex types are:
 108 .Dv PTHREAD_MUTEX_NORMAL ,
 109 .Dv PTHREAD_MUTEX_ERRORCHECK ,
 110 .Dv PTHREAD_MUTEX_RECURSIVE ,
 111 and
 112 .Dv PTHREAD_MUTEX_DEFAULT .
 113 The default mutex type for
 114 .Fn pthread_mutexaddr_init
 115 is
 116 .Dv PTHREAD_MUTEX_DEFAULT .
 117 .Pp
 118 .Dv PTHREAD_MUXEX_NORMAL
 119 mutexes do not check for usage errors.
 120 .Dv PTHREAD_MUTEX_NORMAL
 121 mutexes will deadlock if reentered, and result in undefined behavior if a
 122 locked mutex is unlocked by another thread.  Attempts to unlock an already
 123 unlocked
 124 .Dv PTHREAD_MUTEX_NORMAL
 125 mutex will result in undefined behavior.
 126 .Pp
 127 .Dv PTHREAD_MUTEX_ERRORCHECK
 128 mutexes do check for usage errors.
 129 If an attempt is made to relock a
 130 .Dv PTHREAD_MUTEX_ERRORCHECK
 131 mutex without first dropping the lock an error will be returned.  If a thread
 132 attempts to unlock a
 133 .Dv PTHREAD_MUTEX_ERRORCHECK
 134 mutex that is locked by another thread, an error will be returned.  If a
 135 thread attemps to unlock a
 136 .Dv PTHREAD_MUTEX_ERRORCHECK
 137 thread that is unlocked, an error will be
 138 returned.
 139 .Pp
 140 .Dv PTHREAD_MUTEX_RECURSIVE
 141 mutexes allow recursive locking.
 142 An attempt to relock a
 143 .Dv PTHREAD_MUTEX_RECURSIVE
 144 mutex that is already locked by the same thread succeeds.  An equivalent
 145 number of
 146 .Xr pthread_mutex_unlock 3
 147 calls are needed before the mutex will wake another thread waiting on this
 148 lock.  If a thread attempts to unlock a
 149 .Dv PTHREAD_MUTEX_RECURSIVE
 150 mutex that is locked by another thread, an error will be returned.  If a thread attemps to unlock a
 151 .Dv PTHREAD_MUTEX_RECURSIVE
 152 thread that is unlocked, an error will be returned.
 153 .Pp
 154 .Dv PTHREAD_MUTEX_DEFAULT
 155 mutexes result in undefined behavior if reentered.
 156 Unlocking a
 157 .Dv PTHREAD_MUTEX_DEFAULT
 158 mutex locked by another thread will result in undefined behavior.  Attempts to unlock an already
 159 unlocked
 160 .Dv PTHREAD_MUTEX_DEFAULT
 161 mutex will result in undefined behavior.
 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 .Fn pthread_mutexattr_init
 179 will fail if:
 180 .Bl -tag -width Er
 181 .It Bq Er ENOMEM
 182 Out of memory.
 183 .El
 184 .Pp
 185 .Fn pthread_mutexattr_destroy
 186 will fail if:
 187 .Bl -tag -width Er
 188 .It Bq Er EINVAL
 189 Invalid value for
 190 .Fa attr .
 191 .El
 192 .Pp
 193 .Fn pthread_mutexattr_setprioceiling
 194 will fail if:
 195 .Bl -tag -width Er
 196 .It Bq Er EINVAL
 197 Invalid value for
 198 .Fa attr ,
 199 or invalid value for
 200 .Fa prioceiling .
 201 .El
 202 .Pp
 203 .Fn pthread_mutexattr_getprioceiling
 204 will fail if:
 205 .Bl -tag -width Er
 206 .It Bq Er EINVAL
 207 Invalid value for
 208 .Fa attr .
 209 .El
 210 .Pp
 211 .Fn pthread_mutexattr_setprotocol
 212 will fail if:
 213 .Bl -tag -width Er
 214 .It Bq Er EINVAL
 215 Invalid value for
 216 .Fa attr ,
 217 or invalid value for
 218 .Fa protocol .
 219 .El
 220 .Pp
 221 .Fn pthread_mutexattr_getprotocol
 222 will fail if:
 223 .Bl -tag -width Er
 224 .It Bq Er EINVAL
 225 Invalid value for
 226 .Fa attr .
 227 .El
 228 .Pp
 229 .Fn pthread_mutexattr_settype
 230 will fail if:
 231 .Bl -tag -width Er
 232 .It Bq Er EINVAL
 233 Invalid value for
 234 .Fa attr ,
 235 or invalid value for
 236 .Fa type .
 237 .El
 238 .Pp
 239 .Fn pthread_mutexattr_gettype
 240 will fail if:
 241 .Bl -tag -width Er
 242 .It Bq Er EINVAL
 243 Invalid value for
 244 .Fa attr .
 245 .El
 246 .Sh SEE ALSO
 247 .Xr pthread_mutex_init 3
 248 .Sh STANDARDS
 249 .Fn pthread_mutexattr_init
 250 and
 251 .Fn pthread_mutexattr_destroy
 252 conform to
 253 .St -p1003.1-96
 254 .Pp
 255 .Fn pthread_mutexattr_setprioceiling ,
 256 .Fn pthread_mutexattr_getprioceiling ,
 257 .Fn pthread_mutexattr_setprotocol ,
 258 .Fn pthread_mutexattr_getprotocol ,
 259 .Fn pthread_mutexattr_settype ,
 260 and
 261 .Fn pthread_mutexattr_gettype
 262 conform to
 263 .St -susv2