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 June 20, 2006 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 msleep 9 . 67.It Fa wmesg 68The lock message. 69This is used for both debugging output and 70.Xr msleep 9 . 71.It Fa timo 72The timeout value passed to 73.Xr msleep 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_EXCLUPGRADE" 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_EXCLUPGRADE 131Upgrade a shared lock to an exclusive lock. 132Fails with 133.Er EBUSY 134if there is someone ahead of you in line waiting for an upgrade. 135If this call fails, the shared lock is lost. 136Attempts to upgrade an exclusive lock will cause a 137.Xr panic 9 . 138.It Dv LK_UPGRADE 139Upgrade a shared lock to an exclusive lock. 140If this call fails, the shared lock is lost. 141Attempts to upgrade an exclusive lock will cause a 142.Xr panic 9 . 143.It Dv LK_RELEASE 144Release the lock. 145Releasing a lock that is not held can cause a 146.Xr panic 9 . 147.It Dv LK_DRAIN 148Wait for all activity on the lock to end, then mark it decommissioned. 149This is used before freeing a lock that is part of a piece of memory that is 150about to be freed. 151(As documented in 152.In sys/lockmgr.h . ) 153.It Dv LK_SLEEPFAIL 154Fail if operation has slept. 155.It Dv LK_NOWAIT 156Do not allow the call to sleep. 157This can be used to test the lock. 158.It Dv LK_CANRECURSE 159Allow recursion on an exclusive lock. 160For every lock there must be a release. 161.It Dv LK_INTERLOCK 162Unlock the interlock (which should be locked already). 163.El 164.It Fa interlkp 165An interlock mutex for controlling group access to the lock. 166If 167.Dv LK_INTERLOCK 168is specified, 169.Fn lockmgr 170assumes 171.Fa interlkp 172is currently owned and not recursed, and will return it unlocked. 173See 174.Xr mtx_assert 9 . 175.It Fa td 176A thread responsible for this call. 177.Dv NULL 178becomes 179.Dv LK_KERNPROC . 180.El 181.Pp 182The 183.Fn lockstatus 184function returns the status of the lock in relation to the 185.Vt thread 186passed to it. 187Note that if 188.Fa td 189is 190.Dv NULL 191and an exclusive lock is held, 192.Dv LK_EXCLUSIVE 193will be returned. 194.Pp 195The 196.Fn lockmgr_printinfo 197function prints debugging information about the lock. 198It is used primarily by 199.Xr VOP_PRINT 9 200functions. 201.Sh RETURN VALUES 202The 203.Fn lockcount 204function returns an integer greater than or equal to zero. 205.Pp 206The 207.Fn lockmgr 208function returns 0 on success and non-zero on failure. 209.Pp 210The 211.Fn lockstatus 212function returns: 213.Bl -tag -width ".Dv LK_EXCLUSIVE" 214.It Dv LK_EXCLUSIVE 215An exclusive lock is held by the thread 216.Fa td . 217.It Dv LK_EXCLOTHER 218An exclusive lock is held by someone other than the thread 219.Fa td . 220.It Dv LK_SHARED 221A shared lock is held. 222.It Li 0 223The lock is not held by anyone. 224.El 225.Sh ERRORS 226.Fn lockmgr 227fails if: 228.Bl -tag -width Er 229.It Bq Er EBUSY 230.Dv LK_FORCEUPGRADE 231was requested and another thread had already requested a lock upgrade. 232.It Bq Er EBUSY 233.Dv LK_NOWAIT 234was set, and a sleep would have been required. 235.It Bq Er ENOLCK 236.Dv LK_SLEEPFAIL 237was set and 238.Fn lockmgr 239did sleep. 240.It Bq Er EINTR 241.Dv PCATCH 242was set in the lock priority, and a signal was delivered during a sleep. 243Note the 244.Er ERESTART 245error below. 246.It Bq Er ERESTART 247.Dv PCATCH 248was set in the lock priority, a signal was delivered during a sleep, 249and the system call is to be restarted. 250.It Bq Er EWOULDBLOCK 251a non-zero timeout was given, and the timeout expired. 252.El 253.Sh LOCKS 254If 255.Dv LK_INTERLOCK 256is passed in the 257.Fa flags 258argument to 259.Fn lockmgr , 260the 261.Fa interlkp 262must be held prior to calling 263.Fn lockmgr , 264and will be returned unlocked. 265.Pp 266Upgrade attempts that fail result in the loss of the lock that 267is currently held. 268Also, it is invalid to upgrade an 269exclusive lock, and a 270.Xr panic 9 271will be the result of trying. 272.Sh SEE ALSO 273.Xr msleep 9 , 274.Xr mtx_assert 9 , 275.Xr panic 9 , 276.Xr VOP_PRINT 9 277.Sh AUTHORS 278This manual page was written by 279.An Chad David Aq davidc@acns.ab.ca . 280