xref: /freebsd/share/man/man9/lock.9 (revision 8271a1025c27baa73529ee2a29d0302421fdb71c)

.\" 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$
.\"
.Dd October 24, 2000
.Dt LOCK 9
.Os
.Sh NAME
.Nm lockinit ,
.Nm lockmgr ,
.Nm lockcount ,
.Nm lockstatus
.Nd kernel thread locking
.Sh SYNOPSIS
.In sys/types.h
.In 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 mtx *interlkp" "struct thread *td"
.Ft int
.Fn lockcount "struct lock *lkp"
.Ft int
.Fn lockstatus "struct lock *lkp" "struct thread *td"
.Sh DESCRIPTION
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 ".Dv LK_EXCLUPGRADE"
.It Dv LK_SHARED
get one of many possible shared locks.
If a thread 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 thread holding an exclusive lock may get additional exclusive
locks if it explicitly sets the
.Dv LK_CANRECURSE
flag in the lock request, or if the
.Dv LK_CANRECURSE
flag was set when the lock was initialized.
.It Dv LK_UPGRADE
the thread must hold a shared lock that it wants to
have upgraded to an exclusive lock.
Other threads 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 thread must hold a shared lock that it wants to
have upgraded to an exclusive lock.
If the request succeeds, no other thread 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 thread has already requested an upgrade,
the request will fail.
.It Dv LK_DOWNGRADE
the thread must hold an exclusive lock that it wants
to have downgraded to a shared lock.
If the thread 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
.Fn lockstatus .
Used when another thread holds the lock exclusively.
.El
.Sh RETURN VALUES
Successfully obtained locks return 0.
Locks will always succeed unless one of the following is true:
.Dv LK_FORCEUPGRADE
is requested and some other thread has already
requested a lock upgrade; returns
.Er EBUSY .
.Dv LK_WAIT
is set and a sleep would be required; returns
.Er EBUSY .
.Dv LK_SLEEPFAIL
is set and a sleep was done; returns
.Er ENOLCK .
.Dv 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
.Dv LK_UPGRADE
or
.Dv LK_FORCEUPGRADE
will have released its shared
access lock).