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.1 2004/03/18 15:18:02 eirikn 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(As documented in 147.In sys/lockmgr.h . ) 148.It Dv LK_SLEEPFAIL 149Fail if operation has slept. 150.It Dv LK_NOWAIT 151Do not allow the call to sleep. 152This can be used to test the lock. 153.It Dv LK_CANRECURSE 154Allow recursion on an exclusive lock. 155For every lock there must be a release. 156.It Dv LK_INTERLOCK 157Unlock the interlock (which should be locked already). 158.El 159.It Fa interlkp 160An interlock mutex for controlling group access to the lock. 161If 162.Dv LK_INTERLOCK 163is specified, 164.Fn lockmgr 165assumes 166.Fa interlkp 167is currently owned and not recursed, and will return it unlocked. 168See 169.Xr mtx_assert 9 . 170.It Fa td 171A thread responsible for this call. 172.Dv NULL 173becomes 174.Dv LK_KERNPROC . 175.El 176.Pp 177The 178.Fn lockstatus 179function returns the status of the lock in relation to the 180.Vt thread 181passed to it. 182Note that if 183.Fa td 184is 185.Dv NULL 186and an exclusive lock is held, 187.Dv LK_EXCLUSIVE 188will be returned. 189.Pp 190The 191.Fn lockmgr_printinfo 192function prints debugging information about the lock. 193It is used primarily by 194.Xr VOP_PRINT 9 195functions. 196.Sh RETURN VALUES 197The 198.Fn lockcount 199function returns an integer greater than or equal to zero. 200.Pp 201The 202.Fn lockmgr 203function returns 0 on success and non-zero on failure. 204.Pp 205The 206.Fn lockstatus 207function returns: 208.Bl -tag -width ".Dv LK_EXCLUSIVE" 209.It Dv LK_EXCLUSIVE 210An exclusive lock is held by the thread 211.Fa td . 212.It Dv LK_EXCLOTHER 213An exclusive lock is held by someone other than the thread 214.Fa td . 215.It Dv LK_SHARED 216A shared lock is held. 217.It Li 0 218The lock is not held by anyone. 219.El 220.Sh ERRORS 221.Fn lockmgr 222fails if: 223.Bl -tag -width Er 224.It Bq Er EBUSY 225.Dv LK_NOWAIT 226was set, and a sleep would have been required. 227.It Bq Er ENOLCK 228.Dv LK_SLEEPFAIL 229was set and 230.Fn lockmgr 231did sleep. 232.It Bq Er EINTR 233.Dv PCATCH 234was set in the lock priority, and a signal was delivered during a sleep. 235Note the 236.Er ERESTART 237error below. 238.It Bq Er ERESTART 239.Dv PCATCH 240was set in the lock priority, a signal was delivered during a sleep, 241and the system call is to be restarted. 242.It Bq Er EWOULDBLOCK 243a non-zero timeout was given, and the timeout expired. 244.El 245.Sh LOCKS 246If 247.Dv LK_INTERLOCK 248is passed in the 249.Fa flags 250argument to 251.Fn lockmgr , 252the 253.Fa interlkp 254must be held prior to calling 255.Fn lockmgr , 256and will be returned unlocked. 257.Pp 258Upgrade attempts that fail result in the loss of the lock that 259is currently held. 260Also, it is invalid to upgrade an 261exclusive lock, and a 262.Xr panic 9 263will be the result of trying. 264.Sh SEE ALSO 265.Xr panic 9 , 266.Xr tsleep 9 , 267.Xr VOP_PRINT 9 268.Sh AUTHORS 269This man page was written by 270.An Chad David Aq davidc@acns.ab.ca . 271