130 lines
4.7 KiB
Groff
130 lines
4.7 KiB
Groff
.\" Copyright (c) 2000
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" 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, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, 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 DEVELOPERS ``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 DEVELOPERS 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$
|
|
.\"
|
|
.Dt LOCK 9
|
|
.Os FreeBSD
|
|
.Sh NAME
|
|
.Nm lockinit ,
|
|
.Nm lockmgr ,
|
|
.Nm lockcount ,
|
|
.Nm lockstatus
|
|
.Nd kernel process locking
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <sys/lock.h>
|
|
.Ft void
|
|
.Fn lockinit "struct lock *lkp" "int prio" "char *wmesg" "int timo" "int flags"
|
|
.Ft int
|
|
.Fn lockmgr "struct lock *lkp" "u_int flags" "struct simplelock *interlkp" "struct proc *p"
|
|
.Ft int
|
|
.Fn lockcount "struct lock *lkp"
|
|
.Ft int
|
|
.Fn lockstatus "struct lock *lkp" "struct proc *p"
|
|
.Sh DESCRIPTION
|
|
.Pp
|
|
The function
|
|
.Fn lockinit
|
|
is used to initialise a lock.
|
|
It is required if locks are used.
|
|
The function
|
|
.Fn lockmgr
|
|
is used to manage locks.
|
|
The function
|
|
.Fn lockcount
|
|
returns the number of shared lock holders on a lock.
|
|
The function
|
|
.Fn lockstatus
|
|
determines the status of a lock.
|
|
.Pp
|
|
The following values are defined:
|
|
.Bl -tag -width "LK_XXXXXXXXXXXX" -compact
|
|
.It Dv LK_SHARED
|
|
get one of many possible shared locks.
|
|
If a process holding an exclusive lock requests a shared lock,
|
|
the exclusive lock(s) will be downgraded to shared locks.
|
|
.It Dv LK_EXCLUSIVE
|
|
stop further shared locks, when they are cleared,
|
|
grant a pending upgrade if it exists, then grant an exclusive
|
|
lock.
|
|
Only one exclusive lock may exist at a time, except that
|
|
a process holding an exclusive lock may get additional exclusive
|
|
locks if it explicitly sets the LK_CANRECURSE flag in the lock
|
|
request, or if the LK_CANRECUSE flag was set when the lock was
|
|
initialized.
|
|
.It Dv LK_UPGRADE
|
|
the process must hold a shared lock that it wants to
|
|
have upgraded to an exclusive lock.
|
|
Other processes may get exclusive access to the resource between
|
|
the time that the upgrade is requested and the time that it is
|
|
granted.
|
|
.It Dv LK_EXCLUPGRADE
|
|
the process must hold a shared lock that it wants to
|
|
have upgraded to an exclusive lock.
|
|
If the request succeeds, no other processes will have gotten
|
|
exclusive access to the resource between the time that the upgrade
|
|
is requested and the time that it is granted.
|
|
However, if another process has already requested an upgrade,
|
|
the request will fail.
|
|
.It Dv LK_DOWNGRADE
|
|
the process must hold an exclusive lock that it wants
|
|
to have downgraded to a shared lock.
|
|
If the process holds multiple (recursive) exclusive locks,
|
|
they will all be downgraded to shared locks.
|
|
.It Dv LK_RELEASE
|
|
release one instance of a lock.
|
|
.It Dv LK_DRAIN
|
|
wait for all activity on the lock to end, then mark it
|
|
decommissioned.
|
|
This feature is used before freeing a lock that is part of a
|
|
piece of memory that is about to be freed.
|
|
.It Dv LK_EXCLOTHER
|
|
return for lockstatus().
|
|
Used when another process holds the lock exclusively.
|
|
.El
|
|
.Sh RETURN VALUES
|
|
Successfully obtained locks return 0.
|
|
Locks will always succeed unless one of the following is true:
|
|
LK_FORCEUPGRADE is requested and some other process has already
|
|
requested a lock upgrade; returns
|
|
.Er EBUSY .
|
|
LK_WAIT is set and a sleep would be required; returns
|
|
.Er EBUSY .
|
|
LK_SLEEPFAIL is set and a sleep was done; returns
|
|
.Er ENOLCK .
|
|
PCATCH is set in lock priority and a signal arrives; returns
|
|
either
|
|
.Er EINTR
|
|
or
|
|
.Er ERESTART
|
|
if system calls is to be restarted.
|
|
Non-null lock timeout and timeout expires; returns
|
|
.Er EWOULDBLOCK .
|
|
A failed lock attempt always returns a non-zero error value.
|
|
No lock is held after an error return (in particular, a failed
|
|
LK_UPGRADE or LK_FORCEUPGRADE will have released its shared
|
|
access lock).
|