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 February 25, 2008 30.Dt LOCK 9 31.Os 32.Sh NAME 33.Nm lockinit , 34.Nm lockdestroy , 35.Nm lockmgr , 36.Nm lockstatus , 37.Nm lockmgr_disown , 38.Nm lockmgr_printinfo , 39.Nm lockmgr_recursed , 40.Nm lockmgr_assert 41.Nd "lockmgr family of functions" 42.Sh SYNOPSIS 43.In sys/types.h 44.In sys/lockmgr.h 45.Ft void 46.Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags" 47.Ft void 48.Fn lockdestroy "struct lock *lkp" 49.Ft int 50.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp" 51.Ft int 52.Fn lockstatus "struct lock *lkp" 53.Ft void 54.Fn lockmgr_disown "struct lock *lkp" 55.Ft void 56.Fn lockmgr_printinfo "struct lock *lkp" 57.Ft int 58.Fn lockmgr_recursed "struct lock *lkp" 59.Pp 60.Cd "options INVARIANTS" 61.Cd "options INVARIANT_SUPPORT" 62.Ft void 63.Fn lockmgr_assert "struct lock *lkp" "int what" 64.Sh DESCRIPTION 65The 66.Fn lockinit 67function is used to initialize a lock. 68It must be called before any operation can be performed on a lock. 69Its arguments are: 70.Bl -tag -width ".Fa wmesg" 71.It Fa lkp 72A pointer to the lock to initialize. 73.It Fa prio 74The priority passed to 75.Xr sleep 9 . 76.It Fa wmesg 77The lock message. 78This is used for both debugging output and 79.Xr sleep 9 . 80.It Fa timo 81The timeout value passed to 82.Xr sleep 9 . 83.It Fa flags 84The flags the lock is to be initialized with. 85.Bl -tag -width ".Dv LK_CANRECURSE" 86.It Dv LK_NOWAIT 87Do not sleep while acquiring the lock. 88.It Dv LK_SLEEPFAIL 89Fail after a sleep. 90.It Dv LK_CANRECURSE 91Allow recursive exclusive locks. 92.It Dv LK_NOSHARE 93Allow exclusive locks only. 94.It Dv LK_NOWITNESS 95Instruct 96.Xr witness 4 97to ignore this lock. 98.It Dv LK_NODUP 99.Xr witness 4 100should log messages about duplicate locks being acquired. 101.It Dv LK_TIMELOCK 102Use 103.Fa timo 104during a sleep; otherwise, 0 is used. 105.El 106.El 107.Pp 108The 109.Fn lockdestroy 110function is used to destroy a lock, and while it is called in a number of 111places in the kernel, it currently does nothing. 112.Pp 113The 114.Fn lockmgr 115function handles general locking functionality within the kernel, including 116support for shared and exclusive locks, and recursion. 117.Fn lockmgr 118is also able to upgrade and downgrade locks. 119.Pp 120Its arguments are: 121.Bl -tag -width ".Fa interlkp" 122.It Fa lkp 123A pointer to the lock to manipulate. 124.It Fa flags 125Flags indicating what action is to be taken. 126.Bl -tag -width ".Dv LK_CANRECURSE" 127.It Dv LK_SHARED 128Acquire a shared lock. 129If an exclusive lock is currently held, it will be downgraded. 130.It Dv LK_EXCLUSIVE 131Acquire an exclusive lock. 132If an exclusive lock is already held, and 133.Dv LK_CANRECURSE 134is not set, the system will 135.Xr panic 9 . 136.It Dv LK_DOWNGRADE 137Downgrade exclusive lock to a shared lock. 138Downgrading a shared lock is not permitted. 139If an exclusive lock has been recursed, all references will be downgraded. 140.It Dv LK_UPGRADE 141Upgrade a shared lock to an exclusive lock. 142If this call fails, the shared lock is lost. 143During the upgrade, the shared lock could 144be temporarily dropped. 145Attempts to upgrade an exclusive lock will cause a 146.Xr panic 9 . 147.It Dv LK_RELEASE 148Release the lock. 149Releasing a lock that is not held can cause a 150.Xr panic 9 . 151.It Dv LK_DRAIN 152Wait for all activity on the lock to end, then mark it decommissioned. 153This is used before freeing a lock that is part of a piece of memory that is 154about to be freed. 155(As documented in 156.In sys/lockmgr.h . ) 157.It Dv LK_SLEEPFAIL 158Fail if operation has slept. 159.It Dv LK_NOWAIT 160Do not allow the call to sleep. 161This can be used to test the lock. 162.It Dv LK_CANRECURSE 163Allow recursion on an exclusive lock. 164For every lock there must be a release. 165.It Dv LK_INTERLOCK 166Unlock the interlock (which should be locked already). 167.El 168.It Fa interlkp 169An interlock mutex for controlling group access to the lock. 170If 171.Dv LK_INTERLOCK 172is specified, 173.Fn lockmgr 174assumes 175.Fa interlkp 176is currently owned and not recursed, and will return it unlocked. 177See 178.Xr mtx_assert 9 . 179.El 180.Pp 181The 182.Fn lockstatus 183function returns the status of the lock in relation to the current thread. 184.Pp 185The 186.Fn lockmgr_disown 187function switches the owner from the current thread to be 188.Dv LK_KERNPROC, 189if the lock is already held. 190.Pp 191The 192.Fn lockmgr_printinfo 193function prints debugging information about the lock. 194It is used primarily by 195.Xr VOP_PRINT 9 196functions. 197.Pp 198The 199.Fn lockmgr_recursed 200function returns true if the lock is recursed, 0 201otherwise. 202.Pp 203When compiled with 204.Cd "options INVARIANTS" 205and 206.Cd "options INVARIANT_SUPPORT" , 207the 208.Fn lockmgr_assert 209function tests 210.Fa lkp 211for the assertions specified in 212.Fa what , 213and panics if they are not met. 214One of the following assertions must be specified: 215.Bl -tag -width ".Dv KA_UNLOCKED" 216.It Dv KA_LOCKED 217Assert that the current thread has either a shared or an exclusive lock on the 218.Vt lkp 219lock pointed to by the first argument. 220.It Dv KA_SLOCKED 221Assert that the current thread has a shared lock on the 222.Vt lkp 223lock pointed to by the first argument. 224.It Dv KA_XLOCKED 225Assert that the current thread has an exclusive lock on the 226.Vt lkp 227lock pointed to by the first argument. 228.It Dv KA_UNLOCKED 229Assert that the current thread has no lock on the 230.Vt lkp 231lock pointed to by the first argument. 232.It Dv KA_HELD 233Assert that an unspecified thread has a lock on the 234.Vt lkp 235lock pointed to by the first argument. 236.It Dv KA_UNHELD 237Assert that no thread has a lock on the 238.Vt lkp 239lock pointed to by the first argument. 240.El 241.Pp 242In addition, one of the following optional assertions can be used with 243either an 244.Dv KA_LOCKED , 245.Dv KA_SLOCKED , 246or 247.Dv KA_XLOCKED 248assertion: 249.Bl -tag -width ".Dv KA_NOTRECURSED" 250.It Dv KA_RECURSED 251Assert that the current thread has a recursed lock on 252.Fa lkp . 253.It Dv KA_NOTRECURSED 254Assert that the current thread does not have a recursed lock on 255.Fa lkp . 256.El 257.Pp 258Note that 259.Dv KA_HELD 260and 261.Dv KA_UNHELD 262usage is highly discouraged. 263They are intended to cater a bad behaviour 264introduced by buffer cache lock handling. 265They will hopefully be 266made useless by revisiting such locks. 267.Sh RETURN VALUES 268The 269.Fn lockmgr 270function returns 0 on success and non-zero on failure. 271.Pp 272The 273.Fn lockstatus 274function returns: 275.Bl -tag -width ".Dv LK_EXCLUSIVE" 276.It Dv LK_EXCLUSIVE 277An exclusive lock is held by the current thread. 278.It Dv LK_EXCLOTHER 279An exclusive lock is held by someone other than the current thread. 280.It Dv LK_SHARED 281A shared lock is held. 282.It Li 0 283The lock is not held by anyone. 284.El 285.Sh ERRORS 286.Fn lockmgr 287fails if: 288.Bl -tag -width Er 289.It Bq Er EBUSY 290.Dv LK_FORCEUPGRADE 291was requested and another thread had already requested a lock upgrade. 292.It Bq Er EBUSY 293.Dv LK_NOWAIT 294was set, and a sleep would have been required. 295.It Bq Er ENOLCK 296.Dv LK_SLEEPFAIL 297was set and 298.Fn lockmgr 299did sleep. 300.It Bq Er EINTR 301.Dv PCATCH 302was set in the lock priority, and a signal was delivered during a sleep. 303Note the 304.Er ERESTART 305error below. 306.It Bq Er ERESTART 307.Dv PCATCH 308was set in the lock priority, a signal was delivered during a sleep, 309and the system call is to be restarted. 310.It Bq Er EWOULDBLOCK 311a non-zero timeout was given, and the timeout expired. 312.El 313.Sh LOCKS 314If 315.Dv LK_INTERLOCK 316is passed in the 317.Fa flags 318argument to 319.Fn lockmgr , 320the 321.Fa interlkp 322must be held prior to calling 323.Fn lockmgr , 324and will be returned unlocked. 325.Pp 326Upgrade attempts that fail result in the loss of the lock that 327is currently held. 328Also, it is invalid to upgrade an 329exclusive lock, and a 330.Xr panic 9 331will be the result of trying. 332.Sh SEE ALSO 333.Xr condvar 9 , 334.Xr locking 9 , 335.Xr mutex 9 , 336.Xr rwlock 9 , 337.Xr sleep 9 , 338.Xr sx 9 , 339.Xr mtx_assert 9 , 340.Xr panic 9 , 341.Xr VOP_PRINT 9 342.Sh AUTHORS 343This manual page was written by 344.An Chad David Aq davidc@acns.ab.ca . 345