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