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