lib/libpthread/pthread_mutexattr.3

   1 .\" $NetBSD: pthread_mutexattr.3,v 1.8 2008/05/04 19:43:05 martin 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 .\" 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: src/lib/libpthread/man/pthread_mutexattr.3,v 1.8 2002/09/16 19:29:29 mini Exp $
  53 .Dd January 30, 2003
  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 LIBRARY
  67 .Lb libpthread
  68 .Sh SYNOPSIS
  69 .In pthread.h
  70 .Ft int
  71 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
  72 .Ft int
  73 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
  74 .\" .Ft int
  75 .\" .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"
  76 .\" .Ft int
  77 .\" .Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *prioceiling"
  78 .\" .Ft int
  79 .\" .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
  80 .\" .Ft int
  81 .\" .Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
  82 .Ft int
  83 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
  84 .Ft int
  85 .Fn pthread_mutexattr_gettype "pthread_mutexattr_t * restrict attr" "int * restrict type"
  86 .Sh DESCRIPTION
  87 Mutex attributes are used to specify parameters to
  88 .Fn pthread_mutex_init .
  89 One attribute object can be used in multiple calls to
  90 .Fn pthread_mutex_init ,
  91 with or without modifications between calls.
  92 .Pp
  93 The
  94 .Fn pthread_mutexattr_init
  95 function initializes
  96 .Fa attr
  97 with all the default mutex attributes.
  98 .Pp
  99 The
 100 .Fn pthread_mutexattr_destroy
 101 function destroys
 102 .Fa attr .
 103 .Pp
 104 The
 105 .Fn pthread_mutexattr_settype
 106 functions set the mutex type value of the attribute.
 107 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_MUTEX_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.
 123 Attempts to unlock an already 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.
 132 If a thread attempts to unlock a
 133 .Dv PTHREAD_MUTEX_ERRORCHECK
 134 mutex that is locked by another thread, an error will be returned.
 135 If a thread attempts 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.
 145 An equivalent number of
 146 .Xr pthread_mutex_unlock 3
 147 calls are needed before the mutex will wake another thread waiting
 148 on this lock.
 149 If a thread attempts to unlock a
 150 .Dv PTHREAD_MUTEX_RECURSIVE
 151 mutex that is locked by another thread, an error will be returned.
 152 If a thread attempts to unlock a
 153 .Dv PTHREAD_MUTEX_RECURSIVE
 154 thread that is unlocked, an error will be returned.
 155 .Pp
 156 .Dv PTHREAD_MUTEX_DEFAULT
 157 mutexes result in undefined behavior if reentered.
 158 Unlocking a
 159 .Dv PTHREAD_MUTEX_DEFAULT
 160 mutex locked by another thread will result in undefined behavior.
 161 Attempts to unlock an already unlocked
 162 .Dv PTHREAD_MUTEX_DEFAULT
 163 mutex will result in undefined behavior.
 164 .Pp
 165 .Fn pthread_mutexattr_gettype
 166 functions copy the type value of the attribute to the location
 167 pointed to by the second parameter.
 168 .Sh RETURN VALUES
 169 If successful, these functions return 0.
 170 Otherwise, an error number is returned to indicate the error.
 171 .Sh ERRORS
 172 .Fn pthread_mutexattr_init
 173 shall fail if:
 174 .Bl -tag -width Er
 175 .It Bq Er ENOMEM
 176 Insufficient memory exists to initialize the mutex attributes object.
 177 .El
 178 .Pp
 179 .Fn pthread_mutexattr_settype
 180 shall fail if:
 181 .Bl -tag -width Er
 182 .It Bq Er EINVAL
 183 The value specified by
 184 .Fa type
 185 is invalid.
 186 .El
 187 .\" .Pp
 188 .\" .Fn pthread_mutexattr_setprioceiling
 189 .\" may fail if:
 190 .\" .Bl -tag -width Er
 191 .\" .It Bq Er EINVAL
 192 .\" Invalid value for
 193 .\" .Fa attr ,
 194 .\" or invalid value for
 195 .\" .Fa prioceiling .
 196 .\" .El
 197 .\" .Pp
 198 .\" .Fn pthread_mutexattr_getprioceiling
 199 .\" may fail if:
 200 .\" .Bl -tag -width Er
 201 .\" .It Bq Er EINVAL
 202 .\" Invalid value for
 203 .\" .Fa attr .
 204 .\" .El
 205 .\" .Pp
 206 .\" .Fn pthread_mutexattr_setprotocol
 207 .\" may fail if:
 208 .\" .Bl -tag -width Er
 209 .\" .It Bq Er EINVAL
 210 .\" Invalid value for
 211 .\" .Fa attr ,
 212 .\" or invalid value for
 213 .\" .Fa protocol .
 214 .\" .El
 215 .\" .Pp
 216 .\" .Fn pthread_mutexattr_getprotocol
 217 .\" may fail if:
 218 .\" .Bl -tag -width Er
 219 .\" .It Bq Er EINVAL
 220 .\" Invalid value for
 221 .\" .Fa attr .
 222 .\" .El
 223 .\" .Pp
 224 .Pp
 225 .Fn pthread_mutexattr_destroy ,
 226 .Fn pthread_mutexattr_settype ,
 227 and
 228 .Fn pthread_mutexattr_gettype
 229 may fail if:
 230 .Bl -tag -width Er
 231 .It Bq Er EINVAL
 232 Invalid value for
 233 .Fa attr .
 234 .El
 235 .Sh SEE ALSO
 236 .Xr pthread_mutex_init 3
 237 .Sh STANDARDS
 238 .Fn pthread_mutexattr_init ,
 239 .Fn pthread_mutexattr_destroy ,
 240 .Fn pthread_mutexattr_settype ,
 241 .\" .Fn pthread_mutexattr_setprioceiling ,
 242 .\" .Fn pthread_mutexattr_getprioceiling ,
 243 .\" .Fn pthread_mutexattr_setprotocol ,
 244 .\" .Fn pthread_mutexattr_getprotocol ,
 245 and
 246 .Fn pthread_mutexattr_gettype
 247 conform to
 248 .St -p1003.1-96 .