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