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