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 2, 2014 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_NODDLKTREAT" 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, even if the 168.Dv LK_NOWAIT 169flag is specified. 170During the upgrade, the shared lock could 171be temporarily dropped. 172Attempts to upgrade an exclusive lock will cause a 173.Xr panic 9 . 174.It Dv LK_TRYUPGRADE 175Try to upgrade a shared lock to an exclusive lock. 176The failure to upgrade does not result in the dropping 177of the shared lock ownership. 178.It Dv LK_RELEASE 179Release the lock. 180Releasing a lock that is not held can cause a 181.Xr panic 9 . 182.It Dv LK_DRAIN 183Wait for all activity on the lock to end, then mark it decommissioned. 184This is used before freeing a lock that is part of a piece of memory that is 185about to be freed. 186(As documented in 187.In sys/lockmgr.h . ) 188.It Dv LK_SLEEPFAIL 189Fail if operation has slept. 190.It Dv LK_NOWAIT 191Do not allow the call to sleep. 192This can be used to test the lock. 193.It Dv LK_NOWITNESS 194Skip the 195.Xr witness 4 196checks for this instance. 197.It Dv LK_CANRECURSE 198Allow recursion on an exclusive lock. 199For every lock there must be a release. 200.It Dv LK_INTERLOCK 201Unlock the interlock (which should be locked already). 202.It Dv LK_NODDLKTREAT 203Normally, 204.Fn lockmgr 205postpones serving further shared requests for shared-locked lock if there is 206exclusive waiter, to avoid exclusive lock starvation. 207But, if the thread requesting the shared lock already owns a shared lockmgr 208lock, the request is granted even in presence of the parallel exclusive lock 209request, which is done to avoid deadlocks with recursive shared acquisition. 210.Pp 211The 212.Dv LK_NODDLKTREAT 213flag can only be used by code which requests shared non-recursive lock. 214The flag allows exclusive requests to preempt the current shared request 215even if the current thread owns shared locks. 216This is safe since shared lock is guaranteed to not recurse, and is used 217when thread is known to held unrelated shared locks, to not cause 218unnecessary starvation. 219An example is 220.Dv vp 221locking in VFS 222.Xr lookup 9 , 223when 224.Dv dvp 225is already locked. 226.El 227.It Fa ilk 228An interlock mutex for controlling group access to the lock. 229If 230.Dv LK_INTERLOCK 231is specified, 232.Fn lockmgr 233and 234.Fn lockmgr_rw 235assume 236.Fa ilk 237is currently owned and not recursed, and will return it unlocked. 238See 239.Xr mtx_assert 9 . 240.El 241.Pp 242The 243.Fn lockmgr_args 244and 245.Fn lockmgr_args_rw 246function work like 247.Fn lockmgr 248and 249.Fn lockmgr_rw 250but accepting a 251.Fa wmesg , 252.Fa timo 253and 254.Fa prio 255on a per-instance basis. 256The specified values will override the default 257ones, but this can still be used passing, respectively, 258.Dv LK_WMESG_DEFAULT , 259.Dv LK_PRIO_DEFAULT 260and 261.Dv LK_TIMO_DEFAULT . 262.Pp 263The 264.Fn lockmgr_disown 265function switches the owner from the current thread to be 266.Dv LK_KERNPROC , 267if the lock is already held. 268.Pp 269The 270.Fn lockmgr_printinfo 271function prints debugging information about the lock. 272It is used primarily by 273.Xr VOP_PRINT 9 274functions. 275.Pp 276The 277.Fn lockmgr_recursed 278function returns true if the lock is recursed, 0 279otherwise. 280.Pp 281The 282.Fn lockmgr_waiters 283function returns true if the lock has waiters, 0 otherwise. 284.Pp 285The 286.Fn lockstatus 287function returns the status of the lock in relation to the current thread. 288.Pp 289When compiled with 290.Cd "options INVARIANTS" 291and 292.Cd "options INVARIANT_SUPPORT" , 293the 294.Fn lockmgr_assert 295function tests 296.Fa lkp 297for the assertions specified in 298.Fa what , 299and panics if they are not met. 300One of the following assertions must be specified: 301.Bl -tag -width ".Dv KA_UNLOCKED" 302.It Dv KA_LOCKED 303Assert that the current thread has either a shared or an exclusive lock on the 304.Vt lkp 305lock pointed to by the first argument. 306.It Dv KA_SLOCKED 307Assert that the current thread has a shared lock on the 308.Vt lkp 309lock pointed to by the first argument. 310.It Dv KA_XLOCKED 311Assert that the current thread has an exclusive lock on the 312.Vt lkp 313lock pointed to by the first argument. 314.It Dv KA_UNLOCKED 315Assert that the current thread has no lock on the 316.Vt lkp 317lock pointed to by the first argument. 318.El 319.Pp 320In addition, one of the following optional assertions can be used with 321either an 322.Dv KA_LOCKED , 323.Dv KA_SLOCKED , 324or 325.Dv KA_XLOCKED 326assertion: 327.Bl -tag -width ".Dv KA_NOTRECURSED" 328.It Dv KA_RECURSED 329Assert that the current thread has a recursed lock on 330.Fa lkp . 331.It Dv KA_NOTRECURSED 332Assert that the current thread does not have a recursed lock on 333.Fa lkp . 334.El 335.Sh RETURN VALUES 336The 337.Fn lockmgr 338and 339.Fn lockmgr_rw 340functions return 0 on success and non-zero on failure. 341.Pp 342The 343.Fn lockstatus 344function returns: 345.Bl -tag -width ".Dv LK_EXCLUSIVE" 346.It Dv LK_EXCLUSIVE 347An exclusive lock is held by the current thread. 348.It Dv LK_EXCLOTHER 349An exclusive lock is held by someone other than the current thread. 350.It Dv LK_SHARED 351A shared lock is held. 352.It Li 0 353The lock is not held by anyone. 354.El 355.Sh ERRORS 356.Fn lockmgr 357and 358.Fn lockmgr_rw 359fail if: 360.Bl -tag -width Er 361.It Bq Er EBUSY 362.Dv LK_FORCEUPGRADE 363was requested and another thread had already requested a lock upgrade. 364.It Bq Er EBUSY 365.Dv LK_NOWAIT 366was set, and a sleep would have been required, or 367.Dv LK_TRYUPGRADE 368operation was not able to upgrade the lock. 369.It Bq Er ENOLCK 370.Dv LK_SLEEPFAIL 371was set and 372.Fn lockmgr 373or 374.Fn lockmgr_rw 375did sleep. 376.It Bq Er EINTR 377.Dv PCATCH 378was set in the lock priority, and a signal was delivered during a sleep. 379Note the 380.Er ERESTART 381error below. 382.It Bq Er ERESTART 383.Dv PCATCH 384was set in the lock priority, a signal was delivered during a sleep, 385and the system call is to be restarted. 386.It Bq Er EWOULDBLOCK 387a non-zero timeout was given, and the timeout expired. 388.El 389.Sh LOCKS 390If 391.Dv LK_INTERLOCK 392is passed in the 393.Fa flags 394argument to 395.Fn lockmgr 396or 397.Fn lockmgr_rw , 398the 399.Fa ilk 400must be held prior to calling 401.Fn lockmgr 402or 403.Fn lockmgr_rw , 404and will be returned unlocked. 405.Pp 406Upgrade attempts that fail result in the loss of the lock that 407is currently held. 408Also, it is invalid to upgrade an 409exclusive lock, and a 410.Xr panic 9 411will be the result of trying. 412.Sh SEE ALSO 413.Xr condvar 9 , 414.Xr locking 9 , 415.Xr mtx_assert 9 , 416.Xr mutex 9 , 417.Xr panic 9 , 418.Xr rwlock 9 , 419.Xr sleep 9 , 420.Xr sx 9 , 421.Xr VOP_PRINT 9 422.Sh AUTHORS 423This manual page was written by 424.An Chad David Aq Mt davidc@acns.ab.ca . 425