.\" .\" Copyright (C) 2001 Chad David . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 9, 2001 .Dt LOCKMGR 9 .Os .Sh NAME .Nm lockmgr .Nd "acquires, releases and updates locks" .Sh SYNOPSIS .In sys/types.h .In sys/lockmgr.h .Ft int .Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "struct thread *td" .Sh DESCRIPTION The .Fn lockmgr function handles general locking functionality within the kernel, including support for shared and exclusive locks, and recursion. Locks can also be upgraded and downgraded. .Pp Its arguments are: .Bl -tag -width ".Fa interlkp" .It Fa lkp A pointer to the lock to manipulate. .It Fa flags Flags indicating what action is to be taken. .Bl -tag -width ".Dv LK_EXCLUPGRADE" .It Dv LK_SHARED Acquire a shared lock. If we currently hold an exclusive lock it will be downgraded. .It Dv LK_EXCLUSIVE Acquire an exclusive lock. If we already hold an exclusive lock and .Dv LK_CANRECURSE is not set we will panic. .It Dv LK_DOWNGRADE Downgrade our exclusive lock to a shared lock. Downgrading a shared lock is not valid. If the exclusive lock has been recursed, all references will be downgraded. .It Dv LK_EXCLUPGRADE Upgrade our lock to an exclusive lock. Will fail with .Er EBUSY if there is someone ahead of use waiting for an upgrade. If this call fails we loose our shared lock. Upgrading an exclusive lock will cause a panic. .It Dv LK_UPGRADE Upgrades our lock to an exclusive lock. If this call fails we loose our shared lock. Upgrading an exclusive lock will cause a panic. .It Dv LK_RELEASE Release the lock. Releasing a lock that you do not hold can cause a panic. .It Dv LK_DRAIN Waits for all activity on the lock to end, and then marks it decommissioned. This is used before freeing a lock that is part of a piece of memory that is about to be freed. (As documented in .Pa sys/lockmgr.h . ) .It Dv LK_SLEEPFAIL If we had to sleep for the lock then fail. .It Dv LK_NOWAIT Do not allow the call to sleep. This can be used to test the lock. .It Dv LK_CANRECURSE It is ok to recurse on an exclusive lock. For every lock there must be a release. .It Dv LK_INTERLOCK Unlock the interlock, which is of course locked already. .El .It Fa interlkp An interlock mutex for controlling group access to the lock. If .Dv LK_INTERLOCK is specified, .Fn lockmgr assumes .Fa interlkp is currently owned and not recursed, and will return it unlocked. See .Xr mtx_assert 9 . .It Fa td The thread responsible for this call. .Dv NULL becomes .Dv LK_KERNPROC . .El .Sh LOCKS If .Dv LK_INTERLOCK is specified then .Fa interlkp must be held prior to calling .Fn lockmgr and will be returned unlocked. .Pp Upgrade attempts that fail result in the loss of the lock that is currently held. As well, it is not valid to upgrade an exclusive lock, and a panic will be the result of trying. .Sh RETURN VALUES A value of 0 is returned on success. .Sh ERRORS .Bl -tag -width Er .It Bq Er EBUSY Either .Dv LK_NOWAIT was specified and .Fn lockmgr would have slept, or another thread was ahead of you in line for an exclusive upgrade. .It Bq Er ENOLCK .Dv LK_SLEEP_FAIL was set and we slept. .El .Sh SEE ALSO .Xr lockcount 9 , .Xr lockdestroy 9 , .Xr lockmgr_printinfo 9 , .Xr lockstatus 9 , .Xr mutex 9 .Sh AUTHORS This man page was written by .An Chad David Aq davidc@acns.ab.ca .