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 13, 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" "struct thread *td" 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 184.Vt thread 185passed to it. 186Note that if 187.Fa td 188is 189.Dv NULL 190and an exclusive lock is held, 191.Dv LK_EXCLUSIVE 192will be returned. 193.Pp 194The 195.Fn lockmgr_disown 196function switches the owner from curthread to be 197.Dv LK_KERNPROC, 198if the lock is already held. 199.Pp 200The 201.Fn lockmgr_printinfo 202function prints debugging information about the lock. 203It is used primarily by 204.Xr VOP_PRINT 9 205functions. 206.Pp 207The 208.Fn lockmgr_recursed 209function returns true if the lock is recursed, 0 210otherwise. 211.Pp 212When compiled with 213.Cd "options INVARIANTS" 214and 215.Cd "options INVARIANT_SUPPORT" , 216the 217.Fn lockmgr_assert 218function tests 219.Fa lkp 220for the assertions specified in 221.Fa what , 222and panics if they are not met. 223One of the following assertions must be specified: 224.Bl -tag -width ".Dv KA_UNLOCKED" 225.It Dv KA_LOCKED 226Assert that the current thread has either a shared or an exclusive lock on the 227.Vt lkp 228lock pointed to by the first argument. 229.It Dv KA_SLOCKED 230Assert that the current thread has a shared lock on the 231.Vt lkp 232lock pointed to by the first argument. 233.It Dv KA_XLOCKED 234Assert that the current thread has an exclusive lock on the 235.Vt lkp 236lock pointed to by the first argument. 237.It Dv KA_UNLOCKED 238Assert that the current thread has no lock on the 239.Vt lkp 240lock pointed to by the first argument. 241.It Dv KA_HELD 242Assert that an unspecified thread has a lock on the 243.Vt lkp 244lock pointed to by the first argument. 245.It Dv KA_UNHELD 246Assert that no thread has a lock on the 247.Vt lkp 248lock pointed to by the first argument. 249.El 250.Pp 251In addition, one of the following optional assertions can be used with 252either an 253.Dv KA_LOCKED , 254.Dv KA_SLOCKED , 255or 256.Dv KA_XLOCKED 257assertion: 258.Bl -tag -width ".Dv KA_NOTRECURSED" 259.It Dv KA_RECURSED 260Assert that the current thread has a recursed lock on 261.Fa lkp . 262.It Dv KA_NOTRECURSED 263Assert that the current thread does not have a recursed lock on 264.Fa lkp . 265.El 266.Pp 267Note that 268.Dv KA_HELD 269and 270.Dv KA_UNHELD 271usage is highly discouraged. 272They are intended to cater a bad behaviour 273introduced by buffer cache lock handling. 274They will hopefully be 275made useless by revisiting such locks. 276.Sh RETURN VALUES 277The 278.Fn lockmgr 279function returns 0 on success and non-zero on failure. 280.Pp 281The 282.Fn lockstatus 283function returns: 284.Bl -tag -width ".Dv LK_EXCLUSIVE" 285.It Dv LK_EXCLUSIVE 286An exclusive lock is held by the thread 287.Fa td . 288.It Dv LK_EXCLOTHER 289An exclusive lock is held by someone other than the thread 290.Fa td . 291.It Dv LK_SHARED 292A shared lock is held. 293.It Li 0 294The lock is not held by anyone. 295.El 296.Sh ERRORS 297.Fn lockmgr 298fails if: 299.Bl -tag -width Er 300.It Bq Er EBUSY 301.Dv LK_FORCEUPGRADE 302was requested and another thread had already requested a lock upgrade. 303.It Bq Er EBUSY 304.Dv LK_NOWAIT 305was set, and a sleep would have been required. 306.It Bq Er ENOLCK 307.Dv LK_SLEEPFAIL 308was set and 309.Fn lockmgr 310did sleep. 311.It Bq Er EINTR 312.Dv PCATCH 313was set in the lock priority, and a signal was delivered during a sleep. 314Note the 315.Er ERESTART 316error below. 317.It Bq Er ERESTART 318.Dv PCATCH 319was set in the lock priority, a signal was delivered during a sleep, 320and the system call is to be restarted. 321.It Bq Er EWOULDBLOCK 322a non-zero timeout was given, and the timeout expired. 323.El 324.Sh LOCKS 325If 326.Dv LK_INTERLOCK 327is passed in the 328.Fa flags 329argument to 330.Fn lockmgr , 331the 332.Fa interlkp 333must be held prior to calling 334.Fn lockmgr , 335and will be returned unlocked. 336.Pp 337Upgrade attempts that fail result in the loss of the lock that 338is currently held. 339Also, it is invalid to upgrade an 340exclusive lock, and a 341.Xr panic 9 342will be the result of trying. 343.Sh SEE ALSO 344.Xr condvar 9 , 345.Xr locking 9 , 346.Xr mutex 9 , 347.Xr rwlock 9 , 348.Xr sleep 9 , 349.Xr sx 9 , 350.Xr mtx_assert 9 , 351.Xr panic 9 , 352.Xr VOP_PRINT 9 353.Sh AUTHORS 354This manual page was written by 355.An Chad David Aq davidc@acns.ab.ca . 356