Man page on vn_lock

2 files changed, 91 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 320c96952a2..929f829db38 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.32 2001/02/26 21:15:50 aaron Exp $
+#	$OpenBSD: Makefile,v 1.33 2001/03/10 06:44:17 csapuntz Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -12,7 +12,7 @@ MAN=	audio.9 boot.9 bus_dma.9 bus_space.9 \
 	ratecheck.9 resettodr.9 random.9 shutdownhook_establish.9 \
 	sleep.9 spl.9 store.9 style.9 time.9 timeout.9 uvm.9 \
 	vm_allocate.9 vm_map_copy.9 vm_deallocate.9 \
-	vm_map_inherit.9 vm_map_protect.9 vnode.9
+	vm_map_inherit.9 vm_map_protect.9 vnode.9 vn_lock.9
 
 MLINKS+=bus_dma.9 bus_dmamap_create.9 bus_dma.9 bus_dmamap_destroy.9 \
 	bus_dma.9 bus_dmamap_load.9 bus_dma.9 bus_dmamap_load_mbuf.9 \
diff --git a/share/man/man9/vn_lock.9 b/share/man/man9/vn_lock.9
new file mode 100644
index 00000000000..7d19c006ad2
--- /dev/null
+++ b/share/man/man9/vn_lock.9
@@ -0,0 +1,89 @@
+.Dd March 9, 2001
+.Dt vn_lock 9
+.Os OpenBSD 2.9
+.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.
+
+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.
+
+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
+
+The
+.Fn vn_lock
+function can sleep. The
+.Fn vn_lock
+releases the vnode interlock before exit.
+
+
+.Sh RETURN VALUES
+Upon succesful 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.
+
+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).
+
+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.
+
+The LK_NOWAIT flag does prevent the caller from sleeping.
+
+The locking discipline as it relates to shared locks has yet to be defined.