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 218unneccessary starvation. An example is 219.Dv vp 220locking in VFS 221.Xr lookup 9 , 222when 223.Dv dvp 224is already locked. 225.El 226.It Fa ilk 227An interlock mutex for controlling group access to the lock. 228If 229.Dv LK_INTERLOCK 230is specified, 231.Fn lockmgr 232and 233.Fn lockmgr_rw 234assume 235.Fa ilk 236is currently owned and not recursed, and will return it unlocked. 237See 238.Xr mtx_assert 9 . 239.El 240.Pp 241The 242.Fn lockmgr_args 243and 244.Fn lockmgr_args_rw 245function work like 246.Fn lockmgr 247and 248.Fn lockmgr_rw 249but accepting a 250.Fa wmesg , 251.Fa timo 252and 253.Fa prio 254on a per-instance basis. 255The specified values will override the default 256ones, but this can still be used passing, respectively, 257.Dv LK_WMESG_DEFAULT , 258.Dv LK_PRIO_DEFAULT 259and 260.Dv LK_TIMO_DEFAULT . 261.Pp 262The 263.Fn lockmgr_disown 264function switches the owner from the current thread to be 265.Dv LK_KERNPROC , 266if the lock is already held. 267.Pp 268The 269.Fn lockmgr_printinfo 270function prints debugging information about the lock. 271It is used primarily by 272.Xr VOP_PRINT 9 273functions. 274.Pp 275The 276.Fn lockmgr_recursed 277function returns true if the lock is recursed, 0 278otherwise. 279.Pp 280The 281.Fn lockmgr_waiters 282function returns true if the lock has waiters, 0 otherwise. 283.Pp 284The 285.Fn lockstatus 286function returns the status of the lock in relation to the current thread. 287.Pp 288When compiled with 289.Cd "options INVARIANTS" 290and 291.Cd "options INVARIANT_SUPPORT" , 292the 293.Fn lockmgr_assert 294function tests 295.Fa lkp 296for the assertions specified in 297.Fa what , 298and panics if they are not met. 299One of the following assertions must be specified: 300.Bl -tag -width ".Dv KA_UNLOCKED" 301.It Dv KA_LOCKED 302Assert that the current thread has either a shared or an exclusive lock on the 303.Vt lkp 304lock pointed to by the first argument. 305.It Dv KA_SLOCKED 306Assert that the current thread has a shared lock on the 307.Vt lkp 308lock pointed to by the first argument. 309.It Dv KA_XLOCKED 310Assert that the current thread has an exclusive lock on the 311.Vt lkp 312lock pointed to by the first argument. 313.It Dv KA_UNLOCKED 314Assert that the current thread has no lock on the 315.Vt lkp 316lock pointed to by the first argument. 317.El 318.Pp 319In addition, one of the following optional assertions can be used with 320either an 321.Dv KA_LOCKED , 322.Dv KA_SLOCKED , 323or 324.Dv KA_XLOCKED 325assertion: 326.Bl -tag -width ".Dv KA_NOTRECURSED" 327.It Dv KA_RECURSED 328Assert that the current thread has a recursed lock on 329.Fa lkp . 330.It Dv KA_NOTRECURSED 331Assert that the current thread does not have a recursed lock on 332.Fa lkp . 333.El 334.Sh RETURN VALUES 335The 336.Fn lockmgr 337and 338.Fn lockmgr_rw 339functions return 0 on success and non-zero on failure. 340.Pp 341The 342.Fn lockstatus 343function returns: 344.Bl -tag -width ".Dv LK_EXCLUSIVE" 345.It Dv LK_EXCLUSIVE 346An exclusive lock is held by the current thread. 347.It Dv LK_EXCLOTHER 348An exclusive lock is held by someone other than the current thread. 349.It Dv LK_SHARED 350A shared lock is held. 351.It Li 0 352The lock is not held by anyone. 353.El 354.Sh ERRORS 355.Fn lockmgr 356and 357.Fn lockmgr_rw 358fail if: 359.Bl -tag -width Er 360.It Bq Er EBUSY 361.Dv LK_FORCEUPGRADE 362was requested and another thread had already requested a lock upgrade. 363.It Bq Er EBUSY 364.Dv LK_NOWAIT 365was set, and a sleep would have been required, or 366.Dv LK_TRYUPGRADE 367operation was not able to upgrade the lock. 368.It Bq Er ENOLCK 369.Dv LK_SLEEPFAIL 370was set and 371.Fn lockmgr 372or 373.Fn lockmgr_rw 374did sleep. 375.It Bq Er EINTR 376.Dv PCATCH 377was set in the lock priority, and a signal was delivered during a sleep. 378Note the 379.Er ERESTART 380error below. 381.It Bq Er ERESTART 382.Dv PCATCH 383was set in the lock priority, a signal was delivered during a sleep, 384and the system call is to be restarted. 385.It Bq Er EWOULDBLOCK 386a non-zero timeout was given, and the timeout expired. 387.El 388.Sh LOCKS 389If 390.Dv LK_INTERLOCK 391is passed in the 392.Fa flags 393argument to 394.Fn lockmgr 395or 396.Fn lockmgr_rw , 397the 398.Fa ilk 399must be held prior to calling 400.Fn lockmgr 401or 402.Fn lockmgr_rw , 403and will be returned unlocked. 404.Pp 405Upgrade attempts that fail result in the loss of the lock that 406is currently held. 407Also, it is invalid to upgrade an 408exclusive lock, and a 409.Xr panic 9 410will be the result of trying. 411.Sh SEE ALSO 412.Xr condvar 9 , 413.Xr locking 9 , 414.Xr mutex 9 , 415.Xr rwlock 9 , 416.Xr sleep 9 , 417.Xr sx 9 , 418.Xr mtx_assert 9 , 419.Xr panic 9 , 420.Xr VOP_PRINT 9 421.Sh AUTHORS 422This manual page was written by 423.An Chad David Aq Mt davidc@acns.ab.ca . 424