.\"     $OpenBSD: lock.9,v 1.23 2015/01/11 19:34:52 guenther Exp $
.\"     $NetBSD: lock.9,v 1.12 2001/11/01 01:13:43 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" 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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``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 FOUNDATION OR CONTRIBUTORS
.\" 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.
.\"
.Dd $Mdocdate: January 11 2015 $
.Dt LOCK 9
.Os
.Sh NAME
.Nm lock ,
.Nm lockinit ,
.Nm lockmgr ,
.Nm lockstatus
.Nd kernel lock functions
.Sh SYNOPSIS
.In sys/lock.h
.Ft void
.Fn lockinit "struct lock *lock" "int prio" "const char *wmesg" \
"int timo" "int flags"
.Ft int
.Fn lockmgr "struct lock *lock" "u_int flags" "struct simplelock *slock"
.Ft int
.Fn lockstatus "struct lock *lock"
.Sh DESCRIPTION
The
.Nm
functions provide synchronisation in the kernel by preventing multiple
processes from simultaneously executing critical sections of code
accessing shared data.
.Pp
struct lock supports sleeping until the lock can be acquired.
The lock manager supplies both exclusive-access and
shared-access locks, with recursive exclusive-access locks within a
single process.
It also allows upgrading a shared-access lock to an
exclusive-access lock, as well as downgrading an exclusive-access lock
to a shared-access lock.
.Sh FUNCTIONS
The functions which operate on locks are:
.Bl -tag -width Ds
.It Fn lockinit "lock" "prio" "wmesg" "timo" "flags"
The lock
.Fa lock
is initialised according to the parameters provided.
Arguments are as follows:
.Pp
.Bl -tag -width Ds -compact
.It Fa lock
The lock.
.It Fa prio
The process priority when it is woken up after sleeping on the lock.
.It Fa wmesg
A sleep message used when a process goes to sleep waiting for the lock, so
that the exact reason it is sleeping can easily be identified.
.It Fa timo
The maximum sleep time.
Used by
.Xr tsleep 9 .
.It Fa flags
Flags to specify the lock behaviour permanently over the lifetime of
the lock.
Valid lock flags are:
.Pp
.Bl -tag -width "LK_CANRECURSEXX" -compact
.It LK_NOWAIT
Processes should not sleep when attempting to acquire the lock.
.It LK_CANRECURSE
Processes can acquire the lock recursively.
.El
.El
.It Fn lockmgr "lock" "flags" "slock"
Set, change or release a lock according to the parameters provided.
Arguments are as follows:
.Pp
.Bl -tag -width Ds -compact
.It Fa lock
The lock.
.It Fa flags
Flags to specify the lock request type.
In addition to the flags specified above, the following flags are valid:
.Bl -tag -width Ds
.It LK_SHARED
Get one of many possible shared-access locks.
If a process holding an exclusive-access lock requests a shared-access lock,
the exclusive-access lock is downgraded to a shared-access lock.
.It LK_EXCLUSIVE
Stop further shared-access locks, when they are cleared, grant a
pending upgrade if it exists, then grant an exclusive-access lock.
Only one exclusive-access lock may exist at a time, except that a
process holding an exclusive-access lock may get additional
exclusive-access locks if it explicitly sets the LK_CANRECURSE flag in
the lock request, or if the LK_CANRECURSE flag was set when the lock
was initialised.
.It LK_RELEASE
Release one instance of a lock.
.It 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 LK_RECURSEFAIL
Attempt at recursive lock fails.
.El
.Pp
.It Fa slock
This argument exists for legacy reasons, it is now ignored.
.El
.It Fn lockstatus "lock"
Returns the current state of lock
.Fa lock .
.Pp
.Bl -tag -width "LK_EXCLUSIVE" -offset indent -compact
.It Dv LK_EXCLUSIVE
Lock is locked for exclusive-access by the calling thread.
.It Dv LK_EXCLOTHER
Lock is locked for exclusive-access by a different thread.
.It Dv LK_SHARED
Lock is locked for shared-access.
The current thread may be one of the threads that has it locked.
.It 0
Lock is not locked.
.El
.El
.Sh RETURN VALUES
Successfully acquired locks return 0.
A failed lock attempt always returns a non-zero error value.
No lock is held after an error return.
Locks will always succeed unless one of the following is true:
.Bl -tag -width Er
.It Bq Er EBUSY
LK_NOWAIT is set and a sleep would be required.
.It Bq Er EINTR
PCATCH is set in lock priority and a signal arrives to interrupt
a system call.
.It Bq Er ERESTART
PCATCH is set in lock priority and a signal arrives so that
the system call is restarted.
.It Bq Er EWOULDBLOCK
Non-null lock timeout and timeout expires.
.El
.Sh SEE ALSO
.Xr mutex 9 ,
.Xr pmap 9 ,
.Xr rwlock 9 ,
.Xr spl 9 ,
.Xr tsleep 9 ,
.Xr uvm 9
.Sh HISTORY
The kernel locking API first appeared in
.Bx 4.4 lite2 .
It was progressively deprecated in favor of
.Xr rwlock 9 .