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 December 27, 2007 30.Dt LOCK 9 31.Os 32.Sh NAME 33.Nm lockinit , 34.Nm lockdestroy , 35.Nm lockcount , 36.Nm lockmgr , 37.Nm lockstatus , 38.Nm lockmgr_printinfo 39.Nd "lockmgr family of functions" 40.Sh SYNOPSIS 41.In sys/types.h 42.In sys/lockmgr.h 43.Ft void 44.Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags" 45.Ft void 46.Fn lockdestroy "struct lock *lkp" 47.Ft int 48.Fn lockcount "struct lock *lkp" 49.Ft int 50.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "struct thread *td" 51.Ft int 52.Fn lockstatus "struct lock *lkp" "struct thread *td" 53.Ft void 54.Fn lockmgr_printinfo "struct lock *lkp" 55.Sh DESCRIPTION 56The 57.Fn lockinit 58function is used to initialize a lock. 59It must be called before any operation can be performed on a lock. 60Its arguments are: 61.Bl -tag -width ".Fa wmesg" 62.It Fa lkp 63A pointer to the lock to initialize. 64.It Fa prio 65The priority passed to 66.Xr sleep 9 . 67.It Fa wmesg 68The lock message. 69This is used for both debugging output and 70.Xr sleep 9 . 71.It Fa timo 72The timeout value passed to 73.Xr sleep 9 . 74.It Fa flags 75The flags the lock is to be initialized with. 76.Bl -tag -width ".Dv LG_CANRECURSE" 77.It Dv LK_NOWAIT 78Do not sleep while acquiring the lock. 79.It Dv LK_SLEEPFAIL 80Fail after a sleep. 81.It Dv LK_CANRECURSE 82Allow recursive exclusive locks. 83.It Dv LK_NOSHARE 84Allow exclusive locks only. 85.It Dv LK_TIMELOCK 86Use 87.Fa timo 88during a sleep; otherwise, 0 is used. 89.El 90.El 91.Pp 92The 93.Fn lockdestroy 94function is used to destroy a lock, and while it is called in a number of 95places in the kernel, it currently does nothing. 96.Pp 97The 98.Fn lockcount 99function returns a count of the number of exclusive locks and shared locks 100held against the lock 101.Fa lkp . 102.Pp 103The 104.Fn lockmgr 105function handles general locking functionality within the kernel, including 106support for shared and exclusive locks, and recursion. 107.Fn lockmgr 108is also able to upgrade and downgrade locks. 109.Pp 110Its arguments are: 111.Bl -tag -width ".Fa interlkp" 112.It Fa lkp 113A pointer to the lock to manipulate. 114.It Fa flags 115Flags indicating what action is to be taken. 116.Bl -tag -width ".Dv LK_CANRECURSE" 117.It Dv LK_SHARED 118Acquire a shared lock. 119If an exclusive lock is currently held, it will be downgraded. 120.It Dv LK_EXCLUSIVE 121Acquire an exclusive lock. 122If an exclusive lock is already held, and 123.Dv LK_CANRECURSE 124is not set, the system will 125.Xr panic 9 . 126.It Dv LK_DOWNGRADE 127Downgrade exclusive lock to a shared lock. 128Downgrading a shared lock is not permitted. 129If an exclusive lock has been recursed, all references will be downgraded. 130.It Dv LK_UPGRADE 131Upgrade a shared lock to an exclusive lock. 132If this call fails, the shared lock is lost. 133During the upgrade, the shared lock could 134be temporarily dropped. 135Attempts to upgrade an exclusive lock will cause a 136.Xr panic 9 . 137.It Dv LK_RELEASE 138Release the lock. 139Releasing a lock that is not held can cause a 140.Xr panic 9 . 141.It Dv LK_DRAIN 142Wait for all activity on the lock to end, then mark it decommissioned. 143This is used before freeing a lock that is part of a piece of memory that is 144about to be freed. 145(As documented in 146.In sys/lockmgr.h . ) 147.It Dv LK_SLEEPFAIL 148Fail if operation has slept. 149.It Dv LK_NOWAIT 150Do not allow the call to sleep. 151This can be used to test the lock. 152.It Dv LK_CANRECURSE 153Allow recursion on an exclusive lock. 154For every lock there must be a release. 155.It Dv LK_INTERLOCK 156Unlock the interlock (which should be locked already). 157.El 158.It Fa interlkp 159An interlock mutex for controlling group access to the lock. 160If 161.Dv LK_INTERLOCK 162is specified, 163.Fn lockmgr 164assumes 165.Fa interlkp 166is currently owned and not recursed, and will return it unlocked. 167See 168.Xr mtx_assert 9 . 169.It Fa td 170A thread responsible for this call. 171.Dv NULL 172becomes 173.Dv LK_KERNPROC . 174.El 175.Pp 176The 177.Fn lockstatus 178function returns the status of the lock in relation to the 179.Vt thread 180passed to it. 181Note that if 182.Fa td 183is 184.Dv NULL 185and an exclusive lock is held, 186.Dv LK_EXCLUSIVE 187will be returned. 188.Pp 189The 190.Fn lockmgr_printinfo 191function prints debugging information about the lock. 192It is used primarily by 193.Xr VOP_PRINT 9 194functions. 195.Sh RETURN VALUES 196The 197.Fn lockcount 198function returns an integer greater than or equal to zero. 199.Pp 200The 201.Fn lockmgr 202function returns 0 on success and non-zero on failure. 203.Pp 204The 205.Fn lockstatus 206function returns: 207.Bl -tag -width ".Dv LK_EXCLUSIVE" 208.It Dv LK_EXCLUSIVE 209An exclusive lock is held by the thread 210.Fa td . 211.It Dv LK_EXCLOTHER 212An exclusive lock is held by someone other than the thread 213.Fa td . 214.It Dv LK_SHARED 215A shared lock is held. 216.It Li 0 217The lock is not held by anyone. 218.El 219.Sh ERRORS 220.Fn lockmgr 221fails if: 222.Bl -tag -width Er 223.It Bq Er EBUSY 224.Dv LK_FORCEUPGRADE 225was requested and another thread had already requested a lock upgrade. 226.It Bq Er EBUSY 227.Dv LK_NOWAIT 228was set, and a sleep would have been required. 229.It Bq Er ENOLCK 230.Dv LK_SLEEPFAIL 231was set and 232.Fn lockmgr 233did sleep. 234.It Bq Er EINTR 235.Dv PCATCH 236was set in the lock priority, and a signal was delivered during a sleep. 237Note the 238.Er ERESTART 239error below. 240.It Bq Er ERESTART 241.Dv PCATCH 242was set in the lock priority, a signal was delivered during a sleep, 243and the system call is to be restarted. 244.It Bq Er EWOULDBLOCK 245a non-zero timeout was given, and the timeout expired. 246.El 247.Sh LOCKS 248If 249.Dv LK_INTERLOCK 250is passed in the 251.Fa flags 252argument to 253.Fn lockmgr , 254the 255.Fa interlkp 256must be held prior to calling 257.Fn lockmgr , 258and will be returned unlocked. 259.Pp 260Upgrade attempts that fail result in the loss of the lock that 261is currently held. 262Also, it is invalid to upgrade an 263exclusive lock, and a 264.Xr panic 9 265will be the result of trying. 266.Sh SEE ALSO 267.Xr condvar 9 , 268.Xr locking 9 , 269.Xr mutex 9 , 270.Xr rwlock 9 , 271.Xr sleep 9 , 272.Xr sx 9 , 273.Xr mtx_assert 9 , 274.Xr panic 9 , 275.Xr VOP_PRINT 9 276.Sh AUTHORS 277This manual page was written by 278.An Chad David Aq davidc@acns.ab.ca . 279