share/man/man9/lock.9

   1 .\"
   2 .\" Copyright (C) 2002 Chad David <davidc@acns.ab.ca>. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  18 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  25 .\" DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd March 1, 2008
  30 .Dt LOCK 9
  31 .Os
  32 .Sh NAME
  33 .Nm lockinit ,
  34 .Nm lockdestroy ,
  35 .Nm lockmgr ,
  36 .Nm lockmgr_args ,
  37 .Nm lockmgr_disown ,
  38 .Nm lockmgr_printinfo ,
  39 .Nm lockmgr_recursed ,
  40 .Nm lockstatus ,
  41 .Nm lockmgr_assert
  42 .Nd "lockmgr family of functions"
  43 .Sh SYNOPSIS
  44 .In sys/types.h
  45 .In sys/lock.h
  46 .In sys/lockmgr.h
  47 .Ft void
  48 .Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags"
  49 .Ft void
  50 .Fn lockdestroy "struct lock *lkp"
  51 .Ft int
  52 .Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp"
  53 .Ft int
  54 .Fn lockmgr_args "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "const char *wmesg" "int prio" "int timo"
  55 .Ft void
  56 .Fn lockmgr_disown "struct lock *lkp"
  57 .Ft void
  58 .Fn lockmgr_printinfo "struct lock *lkp"
  59 .Ft int
  60 .Fn lockmgr_recursed "struct lock *lkp"
  61 .Ft int
  62 .Fn lockstatus "struct lock *lkp"
  63 .Pp
  64 .Cd "options INVARIANTS"
  65 .Cd "options INVARIANT_SUPPORT"
  66 .Ft void
  67 .Fn lockmgr_assert "struct lock *lkp" "int what"
  68 .Sh DESCRIPTION
  69 The
  70 .Fn lockinit
  71 function is used to initialize a lock.
  72 It must be called before any operation can be performed on a lock.
  73 Its arguments are:
  74 .Bl -tag -width ".Fa wmesg"
  75 .It Fa lkp
  76 A pointer to the lock to initialize.
  77 .It Fa prio
  78 The priority passed to
  79 .Xr sleep 9 .
  80 .It Fa wmesg
  81 The lock message.
  82 This is used for both debugging output and
  83 .Xr sleep 9 .
  84 .It Fa timo
  85 The timeout value passed to
  86 .Xr sleep 9 .
  87 .It Fa flags
  88 The flags the lock is to be initialized with:
  89 .Bl -tag -width ".Dv LK_CANRECURSE"
  90 .It Dv LK_CANRECURSE
  91 Allow recursive exclusive locks.
  92 .It Dv LK_NOPROFILE
  93 Disable lock profiling for this lock.
  94 .It Dv LK_NOSHARE
  95 Allow exclusive locks only.
  96 .It Dv LK_NOWITNESS
  97 Instruct
  98 .Xr witness 4
  99 to ignore this lock.
 100 .It Dv LK_NODUP
 101 .Xr witness 4
 102 should log messages about duplicate locks being acquired.
 103 .It Dv LK_QUIET
 104 Disable
 105 .Xr ktr 4
 106 logging for this lock.
 107 .It Dv LK_TIMELOCK
 108 Use
 109 .Fa timo
 110 during a sleep; otherwise, 0 is used.
 111 .El
 112 .El
 113 .Pp
 114 The
 115 .Fn lockdestroy
 116 function is used to destroy a lock, and while it is called in a number of
 117 places in the kernel, it currently does nothing.
 118 .Pp
 119 The
 120 .Fn lockmgr
 121 function handles general locking functionality within the kernel, including
 122 support for shared and exclusive locks, and recursion.
 123 .Fn lockmgr
 124 is also able to upgrade and downgrade locks.
 125 .Pp
 126 Its arguments are:
 127 .Bl -tag -width ".Fa interlkp"
 128 .It Fa lkp
 129 A pointer to the lock to manipulate.
 130 .It Fa flags
 131 Flags indicating what action is to be taken.
 132 .Bl -tag -width ".Dv LK_CANRECURSE"
 133 .It Dv LK_SHARED
 134 Acquire a shared lock.
 135 If an exclusive lock is currently held, it will be downgraded.
 136 .It Dv LK_EXCLUSIVE
 137 Acquire an exclusive lock.
 138 If an exclusive lock is already held, and
 139 .Dv LK_CANRECURSE
 140 is not set, the system will
 141 .Xr panic 9 .
 142 .It Dv LK_DOWNGRADE
 143 Downgrade exclusive lock to a shared lock.
 144 Downgrading a shared lock is not permitted.
 145 If an exclusive lock has been recursed, all references will be downgraded.
 146 .It Dv LK_UPGRADE
 147 Upgrade a shared lock to an exclusive lock.
 148 If this call fails, the shared lock is lost.
 149 During the upgrade, the shared lock could
 150 be temporarily dropped.
 151 Attempts to upgrade an exclusive lock will cause a
 152 .Xr panic 9 .
 153 .It Dv LK_RELEASE
 154 Release the lock.
 155 Releasing a lock that is not held can cause a
 156 .Xr panic 9 .
 157 .It Dv LK_DRAIN
 158 Wait for all activity on the lock to end, then mark it decommissioned.
 159 This is used before freeing a lock that is part of a piece of memory that is
 160 about to be freed.
 161 (As documented in
 162 .In sys/lockmgr.h . )
 163 .It Dv LK_SLEEPFAIL
 164 Fail if operation has slept.
 165 .It Dv LK_NOWAIT
 166 Do not allow the call to sleep.
 167 This can be used to test the lock.
 168 .It Dv LK_CANRECURSE
 169 Allow recursion on an exclusive lock.
 170 For every lock there must be a release.
 171 .It Dv LK_INTERLOCK
 172 Unlock the interlock (which should be locked already).
 173 .El
 174 .It Fa interlkp
 175 An interlock mutex for controlling group access to the lock.
 176 If
 177 .Dv LK_INTERLOCK
 178 is specified,
 179 .Fn lockmgr
 180 assumes
 181 .Fa interlkp
 182 is currently owned and not recursed, and will return it unlocked.
 183 See
 184 .Xr mtx_assert 9 .
 185 .El
 186 .Pp
 187 The
 188 .Fn lockmgr_args
 189 function works like
 190 .Fn lockmgr
 191 but accepting a
 192 .Fa wmesg ,
 193 .Fa timo
 194 and
 195 .Fa prio
 196 on a per-instance basis.
 197 The specified values will override the default
 198 ones, but this can still be used passing, respectively,
 199 .Dv LK_WMESG_DEFAULT ,
 200 .Dv LK_PRIO_DEFAULT
 201 and
 202 .Dv LK_TIMO_DEFAULT .
 203 .Pp
 204 The
 205 .Fn lockmgr_disown
 206 function switches the owner from the current thread to be
 207 .Dv LK_KERNPROC,
 208 if the lock is already held.
 209 .Pp
 210 The
 211 .Fn lockmgr_printinfo
 212 function prints debugging information about the lock.
 213 It is used primarily by
 214 .Xr VOP_PRINT 9
 215 functions.
 216 .Pp
 217 The
 218 .Fn lockmgr_recursed
 219 function returns true if the lock is recursed, 0
 220 otherwise.
 221 .Pp
 222 The
 223 .Fn lockstatus
 224 function returns the status of the lock in relation to the current thread.
 225 .Pp
 226 When compiled with
 227 .Cd "options INVARIANTS"
 228 and
 229 .Cd "options INVARIANT_SUPPORT" ,
 230 the
 231 .Fn lockmgr_assert
 232 function tests
 233 .Fa lkp
 234 for the assertions specified in
 235 .Fa what ,
 236 and panics if they are not met.
 237 One of the following assertions must be specified:
 238 .Bl -tag -width ".Dv KA_UNLOCKED"
 239 .It Dv KA_LOCKED
 240 Assert that the current thread has either a shared or an exclusive lock on the
 241 .Vt lkp
 242 lock pointed to by the first argument.
 243 .It Dv KA_SLOCKED
 244 Assert that the current thread has a shared lock on the
 245 .Vt lkp
 246 lock pointed to by the first argument.
 247 .It Dv KA_XLOCKED
 248 Assert that the current thread has an exclusive lock on the
 249 .Vt lkp
 250 lock pointed to by the first argument.
 251 .It Dv KA_UNLOCKED
 252 Assert that the current thread has no lock on the
 253 .Vt lkp
 254 lock pointed to by the first argument.
 255 .It Dv KA_HELD
 256 Assert that an unspecified thread has a lock on the
 257 .Vt lkp
 258 lock pointed to by the first argument.
 259 .It Dv KA_UNHELD
 260 Assert that no thread has a lock on the
 261 .Vt lkp
 262 lock pointed to by the first argument.
 263 .El
 264 .Pp
 265 In addition, one of the following optional assertions can be used with
 266 either an
 267 .Dv KA_LOCKED ,
 268 .Dv KA_SLOCKED ,
 269 or
 270 .Dv KA_XLOCKED
 271 assertion:
 272 .Bl -tag -width ".Dv KA_NOTRECURSED"
 273 .It Dv KA_RECURSED
 274 Assert that the current thread has a recursed lock on
 275 .Fa lkp .
 276 .It Dv KA_NOTRECURSED
 277 Assert that the current thread does not have a recursed lock on
 278 .Fa lkp .
 279 .El
 280 .Pp
 281 Note that
 282 .Dv KA_HELD
 283 and
 284 .Dv KA_UNHELD
 285 usage is highly discouraged.
 286 They are intended to cater a bad behaviour
 287 introduced by buffer cache lock handling.
 288 They will hopefully be
 289 made useless by revisiting such locks.
 290 .Sh RETURN VALUES
 291 The
 292 .Fn lockmgr
 293 function returns 0 on success and non-zero on failure.
 294 .Pp
 295 The
 296 .Fn lockstatus
 297 function returns:
 298 .Bl -tag -width ".Dv LK_EXCLUSIVE"
 299 .It Dv LK_EXCLUSIVE
 300 An exclusive lock is held by the current thread.
 301 .It Dv LK_EXCLOTHER
 302 An exclusive lock is held by someone other than the current thread.
 303 .It Dv LK_SHARED
 304 A shared lock is held.
 305 .It Li 0
 306 The lock is not held by anyone.
 307 .El
 308 .Sh ERRORS
 309 .Fn lockmgr
 310 fails if:
 311 .Bl -tag -width Er
 312 .It Bq Er EBUSY
 313 .Dv LK_FORCEUPGRADE
 314 was requested and another thread had already requested a lock upgrade.
 315 .It Bq Er EBUSY
 316 .Dv LK_NOWAIT
 317 was set, and a sleep would have been required.
 318 .It Bq Er ENOLCK
 319 .Dv LK_SLEEPFAIL
 320 was set and
 321 .Fn lockmgr
 322 did sleep.
 323 .It Bq Er EINTR
 324 .Dv PCATCH
 325 was set in the lock priority, and a signal was delivered during a sleep.
 326 Note the
 327 .Er ERESTART
 328 error below.
 329 .It Bq Er ERESTART
 330 .Dv PCATCH
 331 was set in the lock priority, a signal was delivered during a sleep,
 332 and the system call is to be restarted.
 333 .It Bq Er EWOULDBLOCK
 334 a non-zero timeout was given, and the timeout expired.
 335 .El
 336 .Sh LOCKS
 337 If
 338 .Dv LK_INTERLOCK
 339 is passed in the
 340 .Fa flags
 341 argument to
 342 .Fn lockmgr ,
 343 the
 344 .Fa interlkp
 345 must be held prior to calling
 346 .Fn lockmgr ,
 347 and will be returned unlocked.
 348 .Pp
 349 Upgrade attempts that fail result in the loss of the lock that
 350 is currently held.
 351 Also, it is invalid to upgrade an
 352 exclusive lock, and a
 353 .Xr panic 9
 354 will be the result of trying.
 355 .Sh SEE ALSO
 356 .Xr condvar 9 ,
 357 .Xr locking 9 ,
 358 .Xr mutex 9 ,
 359 .Xr rwlock 9 ,
 360 .Xr sleep 9 ,
 361 .Xr sx 9 ,
 362 .Xr mtx_assert 9 ,
 363 .Xr panic 9 ,
 364 .Xr VOP_PRINT 9
 365 .Sh AUTHORS
 366 This manual page was written by
 367 .An Chad David Aq davidc@acns.ab.ca .