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