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.\" 29.Dd April 10, 2010 30.Dt LOCK 9 31.Os 32.Sh NAME 33.Nm lockinit , 34.Nm lockcount , 35.Nm lockmgr , 36.Nm lockstatus , 37.Nm lockmgr_printinfo 38.Nd "lockmgr family of functions" 39.Sh SYNOPSIS 40.In sys/types.h 41.In sys/lock.h 42.Ft void 43.Fn lockinit "struct lock *lkp" "char *wmesg" "int timo" "int flags" 44.Ft int 45.Fn lockcount "struct lock *lkp" 46.Ft int 47.Fn lockcountnb "struct lock *lkp" 48.Ft int 49.Fn lockmgr "struct lock *lkp" "u_int flags" 50.Ft int 51.Fn lockstatus "struct lock *lkp" "struct thread *td" 52.Ft void 53.Fn lockmgr_printinfo "struct lock *lkp" 54.Sh DESCRIPTION 55The 56.Fn lockinit 57function is used to initialize a lock. 58It must be called before any operation can be performed on a lock. 59Its arguments are: 60.Bl -tag -width ".Fa wmesg" 61.It Fa lkp 62A pointer to the lock to initialize. 63.It Fa wmesg 64The lock message. 65This is used for both debugging output and 66.Xr tsleep 9 . 67.It Fa timo 68The timeout value passed to 69.Xr tsleep 9 . 70.It Fa flags 71The flags the lock is to be initialized with. 72.Bl -tag -width ".Dv LK_CANRECURSE" 73.It Dv LK_NOWAIT 74Do not sleep while acquiring the lock. 75.It Dv LK_SLEEPFAIL 76Fail after a sleep. 77.It Dv LK_CANRECURSE 78Allow recursive exclusive locks. 79.It Dv LK_TIMELOCK 80Use 81.Fa timo 82during a sleep; otherwise, 0 is used. 83.El 84.El 85.Pp 86The 87.Fn lockcount 88function returns a count of the number of exclusive locks and shared locks 89held against the lock 90.Fa lkp . 91.Pp 92The 93.Fn lockcountnb 94function is a non-blocking counter-part of 95.Fn lockcount . 96which, can be safely used in assertion statements e.g. a 97.Xr KASSERT 9 . 98.Pp 99The 100.Fn lockmgr 101function handles general locking functionality within the kernel, including 102support for shared and exclusive locks, and recursion. 103.Fn lockmgr 104is also able to upgrade and downgrade locks. 105.Pp 106Its arguments are: 107.Bl -tag -width ".Fa flags" 108.It Fa lkp 109A pointer to the lock to manipulate. 110.It Fa flags 111Flags indicating what action is to be taken. 112.Bl -tag -width ".Dv LK_EXCLUPGRADE" 113.It Dv LK_SHARED 114Acquire a shared lock. 115If an exclusive lock is currently held, it will be downgraded. 116.It Dv LK_EXCLUSIVE 117Acquire an exclusive lock. 118If an exclusive lock is already held, and 119.Dv LK_CANRECURSE 120is not set, the system will 121.Xr panic 9 . 122.It Dv LK_DOWNGRADE 123Downgrade exclusive lock to a shared lock. 124Downgrading a shared lock is not permitted. 125If an exclusive lock has been recursed, all references will be downgraded. 126.It Dv LK_EXCLUPGRADE 127Upgrade a shared lock to an exclusive lock. 128Fails with 129.Er EBUSY 130if there is someone ahead of you in line waiting for an upgrade. 131If this call fails, the shared lock is lost. 132Attempts to upgrade an exclusive lock will cause a 133.Xr panic 9 . 134.It Dv LK_UPGRADE 135Upgrade a shared lock to an exclusive lock. 136If this call fails, the shared lock is lost. 137Attempts to upgrade an exclusive lock will cause a 138.Xr panic 9 . 139.It Dv LK_RELEASE 140Release the lock. 141Releasing a lock that is not held can cause a 142.Xr panic 9 . 143.It Dv LK_SLEEPFAIL 144Fail if operation has slept. 145.It Dv LK_NOWAIT 146Do not allow the call to sleep. 147This can be used to test the lock. 148.It Dv LK_CANRECURSE 149Allow recursion on an exclusive lock. 150For every lock there must be a release. 151.El 152.El 153.Pp 154The 155.Fn lockstatus 156function returns the status of the lock in relation to the 157.Vt thread 158passed to it. 159Note that if 160.Fa td 161is 162.Dv NULL 163and an exclusive lock is held, 164.Dv LK_EXCLUSIVE 165will be returned. 166.Pp 167The 168.Fn lockmgr_printinfo 169function prints debugging information about the lock. 170It is used primarily by 171.Xr VOP_PRINT 9 172functions. 173.Sh RETURN VALUES 174The 175.Fn lockcount 176function returns an integer greater than or equal to zero. 177.Pp 178The 179.Fn lockmgr 180function returns 0 on success and non-zero on failure. 181.Pp 182The 183.Fn lockstatus 184function returns: 185.Bl -tag -width ".Dv LK_EXCLUSIVE" 186.It Dv LK_EXCLUSIVE 187An exclusive lock is held by the thread 188.Fa td . 189.It Dv LK_EXCLOTHER 190An exclusive lock is held by someone other than the thread 191.Fa td . 192.It Dv LK_SHARED 193A shared lock is held. 194.It Li 0 195The lock is not held by anyone. 196.El 197.Sh FILES 198The lock manager itself is implemented within the file 199.Pa /sys/kern/kern_lock.c . 200Data structures and function prototypes for the lock manager are in 201.Pa /sys/sys/lock.h . 202.Sh ERRORS 203.Fn lockmgr 204fails if: 205.Bl -tag -width Er 206.It Bq Er EBUSY 207.Dv LK_NOWAIT 208was set, and a sleep would have been required. 209.It Bq Er ENOLCK 210.Dv LK_SLEEPFAIL 211was set and 212.Fn lockmgr 213did sleep. 214.It Bq Er EINTR 215.Dv PCATCH 216was set in the lock priority, and a signal was delivered during a sleep. 217Note the 218.Er ERESTART 219error below. 220.It Bq Er ERESTART 221.Dv PCATCH 222was set in the lock priority, a signal was delivered during a sleep, 223and the system call is to be restarted. 224.It Bq Er EWOULDBLOCK 225a non-zero timeout was given, and the timeout expired. 226.El 227.Sh LOCKS 228Upgrade attempts that fail result in the loss of the lock that 229is currently held. 230Also, it is invalid to upgrade an 231exclusive lock, and a 232.Xr panic 9 233will be the result of trying. 234.Sh SEE ALSO 235.Xr panic 9 , 236.Xr tsleep 9 , 237.Xr VOP_PRINT 9 238.Sh HISTORY 239The lock manager appeared in 240.Dx 1.0 . 241.Pp 242The lock manager API first appeared in 243.Bx 4.4 lite2 . 244.Sh AUTHORS 245This man page was written by 246.An Chad David Aq davidc@acns.ab.ca . 247