.\"     $OpenBSD: vn_lock.9,v 1.5 2002/08/26 20:18:07 art Exp $
.\"
.\" Copyright (c) 2001 Constantine Sapuntzakis
.\" 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. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED ``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 AUTHOR 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 March 9, 2001
.Dt VN_LOCK 9
.Os
.Sh NAME
.Nm vn_lock
.Nd acquire the vnode lock
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/vnode.h>
.Ft int
.Fn "vn_lock" "struct vnode *vp" "int flags" "struct proc *p"
.Sh DESCRIPTION
The
.Fn vn_lock
function is used to acquire the vnode lock.
Certain file system operations require that the vnode lock be held when
they are called.
See sys/kern/vnode_if.src for more details.
.Pp
The
.Fn vn_lock
function must not be called when the vnode's reference count is
zero.
Instead, the
.Fn vget
function should be used.
.Pp
The 
.Fa flags 
fields may contain the following flags:
.Bl -column LK_INTERLOCK -offset indent
.It Dv LK_RETRY Ta
Return the vnode even if it has been reclaimed.
.It Dv LK_INTERLOCK Ta
Must be set if the caller owns the vnode interlock.
.It Dv LK_NOWAIT Ta
Don't wait if the vnode lock is held by someone else (may still
wait on reclamation lock on or interlock).
Must not be used with LK_RETRY.
.It Dv LK_EXCLUSIVE Ta
Acquire an exclusive lock
.It Dv LK_SHARED Ta
Acquire a shared lock
.El
.Pp
The
.Fn vn_lock
function can sleep.
The
.Fn vn_lock
releases the vnode interlock before exit.
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, one of the following errors is returned.
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er ENOENT
The vnode has been reclaimed and is dead.
This error is only returned if the LK_RETRY flag is not passed.
.It Bq Er EBUSY
The LK_NOWAIT flag was set and the vn_lock would have slept.
.El
.Sh SEE ALSO
.Xr vnode 9
.Sh BUGS 
The locking discipline is bizarre.
Many vnode operations are passed locked vnodes on entry but release
the lock before they exit.
Discussions with Kirk McKusick indicate that locking
discipline evolved out of the pre-VFS way of doing inode locking.
In addition, the current locking discipline may actually save
lines of code, esp. if the number of file systems is fewer
then the number of call sites.
However, the VFS interface would
require less wizardry if the locking discipline were simpler.
.Pp
The locking discipline is used in some places to attempt to make a
series of operations atomic (e.g., permissions check +
operation).
This does not work for non-local file systems that do not
support locking (e.g., NFS).
.Pp
Are vnode locks even necessary?
The security checks can be moved into the individual file systems.
Each file system can have the responsibility of ensuring that vnode
operations are suitably atomic.
.Pp
The LK_NOWAIT flag does prevent the caller from sleeping.
.Pp
The locking discipline as it relates to shared locks has yet to be defined.