2001-07-10 04:22:14 +00:00
|
|
|
.\"
|
|
|
|
|
.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. 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
|
2001-07-11 10:31:49 +00:00
|
|
|
.Nd "acquires, releases and updates locks"
|
2001-07-10 04:22:14 +00:00
|
|
|
.Sh SYNOPSIS
|
2001-07-11 10:31:49 +00:00
|
|
|
.In sys/types.h
|
|
|
|
|
.In sys/lockmgr.h
|
2001-07-10 04:22:14 +00:00
|
|
|
.Ft int
|
2001-07-11 03:51:44 +00:00
|
|
|
.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *interlkp" "struct proc *p"
|
2001-07-10 04:22:14 +00:00
|
|
|
.Sh DESCRIPTION
|
|
|
|
|
The
|
2001-07-11 10:31:49 +00:00
|
|
|
.Fn lockmgr
|
2001-07-10 04:22:14 +00:00
|
|
|
function handles general locking functionality within the kernel, including
|
2001-07-11 10:31:49 +00:00
|
|
|
support for shared and exclusive locks, and recursion.
|
|
|
|
|
Locks can also be upgraded and downgraded.
|
2001-07-10 04:22:14 +00:00
|
|
|
.Pp
|
|
|
|
|
Its arguments are:
|
2001-07-11 10:31:49 +00:00
|
|
|
.Bl -tag -xwidth ".Fa interlkp"
|
|
|
|
|
.It Fa lkp
|
2001-07-10 04:29:24 +00:00
|
|
|
A pointer to lock to manipulate.
|
2001-07-11 10:31:49 +00:00
|
|
|
.It Fa flags
|
2001-07-10 04:22:14 +00:00
|
|
|
Flags indicating what action is to be taken.
|
2001-07-11 10:31:49 +00:00
|
|
|
.Bl -tag -xwidth ".Dv LK_EXCLUPGRADE"
|
|
|
|
|
.It Dv LK_SHARED
|
|
|
|
|
Aquire a shared lock.
|
|
|
|
|
If we currently hold an exclusive lock it will be downgraded.
|
|
|
|
|
.It Dv LK_EXCLUSIVE
|
|
|
|
|
Aquire 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
|
2001-07-10 04:22:14 +00:00
|
|
|
be downgraded.
|
2001-07-11 10:31:49 +00:00
|
|
|
.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
|
2001-07-10 04:22:14 +00:00
|
|
|
a panic.
|
2001-07-11 10:31:49 +00:00
|
|
|
.It Dv LK_DRAIN
|
|
|
|
|
Waits for all activity on the lock to end, and then marks it decommissioned.
|
2001-07-10 04:22:14 +00:00
|
|
|
This is used before freeing a lock that is part of a piece of memory that is about to
|
2001-07-11 10:31:49 +00:00
|
|
|
be freed.
|
|
|
|
|
(As documented in
|
|
|
|
|
.Pa 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
|
2001-07-10 04:22:14 +00:00
|
|
|
must be a release.
|
2001-07-11 10:31:49 +00:00
|
|
|
.It Dv LK_INTERLOCK
|
|
|
|
|
Unlock the interlock, which is of course locked already.
|
|
|
|
|
.El
|
|
|
|
|
.It Fa interlkp
|
2001-07-10 04:22:14 +00:00
|
|
|
An interlock mutex for controlling group access to the lock.
|
2001-07-11 10:31:49 +00:00
|
|
|
If
|
|
|
|
|
.Dv LK_INTERLOCK
|
|
|
|
|
is specified,
|
|
|
|
|
.Fn lockmgr
|
2001-07-10 04:22:14 +00:00
|
|
|
assumes
|
2001-07-11 10:31:49 +00:00
|
|
|
.Fa interlkp
|
2001-07-10 04:22:14 +00:00
|
|
|
is currently owned and not recursed, and will return it unlocked.
|
2001-07-11 10:31:49 +00:00
|
|
|
See
|
|
|
|
|
.Xr mtx_assert 9 .
|
|
|
|
|
.It Fa p
|
|
|
|
|
The process responsible for this call.
|
|
|
|
|
.Dv NULL
|
|
|
|
|
becomes
|
|
|
|
|
.Dv LK_KERNPROC .
|
2001-07-10 04:22:14 +00:00
|
|
|
.El
|
|
|
|
|
.Sh LOCKS
|
2001-07-11 10:31:49 +00:00
|
|
|
If
|
|
|
|
|
.Dv LK_INTERLOCK
|
|
|
|
|
is specified then
|
|
|
|
|
.Fa interlkp
|
2001-07-10 04:22:14 +00:00
|
|
|
must be held prior to calling
|
2001-07-11 10:31:49 +00:00
|
|
|
.Fn lockmgr
|
2001-07-10 04:22:14 +00:00
|
|
|
and will be returned unlocked.
|
|
|
|
|
.Pp
|
|
|
|
|
Upgrade attempts that fail result in the loss of the lock that
|
2001-07-11 10:31:49 +00:00
|
|
|
is currently held.
|
|
|
|
|
As well, it is not valid to upgrade an
|
2001-07-10 04:22:14 +00:00
|
|
|
exclusive lock, and a panic will be the result of trying.
|
|
|
|
|
.Sh RETURN VALUES
|
2001-07-11 10:31:49 +00:00
|
|
|
A value of 0 is returned on success.
|
2001-07-10 04:22:14 +00:00
|
|
|
.Sh ERRORS
|
2001-07-11 10:31:49 +00:00
|
|
|
.Bl -tag -width Er
|
|
|
|
|
.It Bq Er EBUSY
|
|
|
|
|
Either
|
|
|
|
|
.Dv LK_NOWAIT
|
|
|
|
|
was specified and
|
|
|
|
|
.Fn lockmgr
|
|
|
|
|
would have slept, or another
|
2001-07-10 04:22:14 +00:00
|
|
|
process was ahead of you in line for an exclusive upgrade.
|
2001-07-11 10:31:49 +00:00
|
|
|
.It Bq Er ENOLCK
|
|
|
|
|
.Dv LK_SLEEP_FAIL
|
|
|
|
|
was set and we slept.
|
|
|
|
|
.El
|
2001-07-10 04:22:14 +00:00
|
|
|
.Sh SEE ALSO
|
2001-07-11 10:31:49 +00:00
|
|
|
.Xr lockcount 9 ,
|
|
|
|
|
.Xr lockdestroy 9 ,
|
|
|
|
|
.Xr lockmgr_printinfo 9 ,
|
|
|
|
|
.Xr lockstatus 9 ,
|
2001-07-10 04:22:14 +00:00
|
|
|
.Xr mutex 9
|
|
|
|
|
.Sh AUTHORS
|
2001-07-11 10:31:49 +00:00
|
|
|
This man page was written by
|
|
|
|
|
.An Chad David .
|
