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: src/share/man/man9/lock.9,v 1.11 2003/09/08 19:57:21 ru Exp $ 28.\" $DragonFly: src/share/man/man9/lock.9,v 1.2 2004/05/10 13:06:53 hmp Exp $ 29.\" 30.Dd July 9, 2001 31.Dt LOCK 9 32.Os 33.Sh NAME 34.Nm lockinit , 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/lock.h 43.Ft void 44.Fn lockinit "struct lock *lkp" "int prio" "char *wmesg" "int timo" "int flags" 45.Ft int 46.Fn lockcount "struct lock *lkp" 47.Ft int 48.Fn lockmgr "struct lock *lkp" "u_int flags" "lwkt_tokref_t interlkp" "struct thread *td" 49.Ft int 50.Fn lockstatus "struct lock *lkp" "struct thread *td" 51.Ft void 52.Fn lockmgr_printinfo "struct lock *lkp" 53.Sh DESCRIPTION 54The 55.Fn lockinit 56function is used to initialize a lock. 57It must be called before any operation can be performed on a lock. 58Its arguments are: 59.Bl -tag -width ".Fa wmesg" 60.It Fa lkp 61A pointer to the lock to initialize. 62.It Fa prio 63The priority passed to 64.Xr tsleep 9 . 65.It Fa wmesg 66The lock message. 67This is used for both debugging output and 68.Xr tsleep 9 . 69.It Fa timo 70The timeout value passed to 71.Xr tsleep 9 . 72.It Fa flags 73The flags the lock is to be initialized with. 74.Bl -tag -width ".Dv LG_CANRECURSE" 75.It Dv LK_NOWAIT 76Do not sleep while acquiring the lock. 77.It Dv LK_SLEEPFAIL 78Fail after a sleep. 79.It Dv LK_CANRECURSE 80Allow recursive exclusive locks. 81.It Dv LK_REENABLE 82Re-enable the lock after a drain. 83.It Dv LK_NOPAUSE 84Disable the spinlock while acquiring the lock. 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 lockcount 94function returns a count of the number of exclusive locks and shared locks 95held against the lock 96.Fa lkp . 97.Pp 98The 99.Fn lockmgr 100function handles general locking functionality within the kernel, including 101support for shared and exclusive locks, and recursion. 102.Fn lockmgr 103is also able to upgrade and downgrade locks. 104.Pp 105Its arguments are: 106.Bl -tag -width ".Fa interlkp" 107.It Fa lkp 108A pointer to the lock to manipulate. 109.It Fa flags 110Flags indicating what action is to be taken. 111.Bl -tag -width ".Dv LK_EXCLUPGRADE" 112.It Dv LK_SHARED 113Acquire a shared lock. 114If an exclusive lock is currently held, it will be downgraded. 115.It Dv LK_EXCLUSIVE 116Acquire an exclusive lock. 117If an exclusive lock is already held, and 118.Dv LK_CANRECURSE 119is not set, the system will 120.Xr panic 9 . 121.It Dv LK_DOWNGRADE 122Downgrade exclusive lock to a shared lock. 123Downgrading a shared lock is not permitted. 124If an exclusive lock has been recursed, all references will be downgraded. 125.It Dv LK_EXCLUPGRADE 126Upgrade a shared lock to an exclusive lock. 127Fails with 128.Er EBUSY 129if there is someone ahead of you in line waiting for an upgrade. 130If this call fails, the shared lock is lost. 131Attempts to upgrade an exclusive lock will cause a 132.Xr panic 9 . 133.It Dv LK_UPGRADE 134Upgrade a shared lock to an exclusive lock. 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_RELEASE 139Release the lock. 140Releasing a lock that is not held can cause a 141.Xr panic 9 . 142.It Dv LK_DRAIN 143Wait for all activity on the lock to end, then mark it decommissioned. 144This is used before freeing a lock that is part of a piece of memory that is 145about to be freed. 146.Po 147As documented in 148.Pa sys/lockmgr.h . 149.Pc 150.It Dv LK_SLEEPFAIL 151Fail if operation has slept. 152.It Dv LK_NOWAIT 153Do not allow the call to sleep. 154This can be used to test the lock. 155.It Dv LK_CANRECURSE 156Allow recursion on an exclusive lock. 157For every lock there must be a release. 158.It Dv LK_INTERLOCK 159Unlock the interlock (which should be locked already). 160.El 161.It Fa interlkp 162An interlock mutex for controlling group access to the lock. 163If 164.Dv LK_INTERLOCK 165is specified, 166.Fn lockmgr 167assumes 168.Fa interlkp 169is currently owned and not recursed, and will return it unlocked. 170See 171.Xr mtx_assert 9 . 172.It Fa td 173A thread responsible for this call. 174.Dv NULL 175becomes 176.Dv LK_KERNPROC . 177.El 178.Pp 179The 180.Fn lockstatus 181function returns the status of the lock in relation to the 182.Vt thread 183passed to it. 184Note that if 185.Fa td 186is 187.Dv NULL 188and an exclusive lock is held, 189.Dv LK_EXCLUSIVE 190will be returned. 191.Pp 192The 193.Fn lockmgr_printinfo 194function prints debugging information about the lock. 195It is used primarily by 196.Xr VOP_PRINT 9 197functions. 198.Sh RETURN VALUES 199The 200.Fn lockcount 201function returns an integer greater than or equal to zero. 202.Pp 203The 204.Fn lockmgr 205function returns 0 on success and non-zero on failure. 206.Pp 207The 208.Fn lockstatus 209function returns: 210.Bl -tag -width ".Dv LK_EXCLUSIVE" 211.It Dv LK_EXCLUSIVE 212An exclusive lock is held by the thread 213.Fa td . 214.It Dv LK_EXCLOTHER 215An exclusive lock is held by someone other than the thread 216.Fa td . 217.It Dv LK_SHARED 218A shared lock is held. 219.It Li 0 220The lock is not held by anyone. 221.El 222.Sh ERRORS 223.Fn lockmgr 224fails if: 225.Bl -tag -width Er 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 panic 9 , 268.Xr tsleep 9 , 269.Xr VOP_PRINT 9 270.Sh AUTHORS 271This man page was written by 272.An Chad David Aq davidc@acns.ab.ca . 273