document the vfs_busy class of functions

requested by and ok pedro, feedback jmc

2 files changed, 84 insertions, 3 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 715159021f9..3aa8112c621 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.115 2006/06/24 14:14:30 deraadt Exp $
+#	$OpenBSD: Makefile,v 1.116 2006/07/02 11:54:10 sturm Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -23,8 +23,8 @@ MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \
 	sensor_add.9 \
 	shutdownhook_establish.9 sleep.9 spl.9 startuphook_establish.9 \
 	style.9 syscall.9 systrace.9 sysctl_int.9 \
-	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 vfs_cache.9 \
-	vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \
+	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 vfs_busy.9 \
+	vfs_cache.9 vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \
 	vflushbuf.9 vget.9 vgone.9 vhold.9 vinvalbuf.9 vnode.9 vnsubr.9 \
 	VOP_GETATTR.9 VOP_LOOKUP.9 vput.9 vrecycle.9 vref.9 vrele.9 \
 	vwaitforio.9 vwakeup.9 wdog_register.9
@@ -298,6 +298,7 @@ MLINKS+=kern.9 imax.9 kern.9 imin.9 kern.9 lmax.9 kern.9 lmin.9 \
 	kern.9 strcmp.9 kern.9 strncmp.9 kern.9 strncasecmp.9 \
 	kern.9 srandom.9 kern.9 getsn.9
 
+MLINKS+=vfs_busy.9 vfs_isbusy.9 vfs_busy.9 vfs_unbusy.9
 MLINKS+=vfs_cache.9 cache_enter.9 vfs_cache.9 cache_lookup.9 \
 	vfs_cache.9 cache_purge.9 vfs_cache.9 cache_purgevfs.9 \
 	vfs_cache.9 cache_revlookup.9
diff --git a/share/man/man9/vfs_busy.9 b/share/man/man9/vfs_busy.9
new file mode 100644
index 00000000000..f9a0aff4382
--- /dev/null
+++ b/share/man/man9/vfs_busy.9
@@ -0,0 +1,80 @@
+.\"	$OpenBSD: vfs_busy.9,v 1.1 2006/07/02 11:54:10 sturm Exp $
+.\"
+.\" Copyright (c) 2006 Nikolay Sturm <sturm@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd June 17, 2006
+.Dt VFS_BUSY 9
+.Os
+.Sh NAME
+.Nm vfs_busy ,
+.Nm vfs_isbusy ,
+.Nm vfs_unbusy
+.Nd VFS locking API
+.Sh SYNOPSIS
+.In sys/mount.h
+.Pp
+.Ft int
+.Fn vfs_busy "struct mount *mp" "int flags"
+.Ft int
+.Fn vfs_isbusy "struct mount *mp"
+.Ft void
+.Fn vfs_unbusy "struct mount *mp"
+.Sh DESCRIPTION
+The
+.Nm vfs_busy
+API is used to lock mount points to ensure consistent access.
+A read lock can be shared between multiple processes, while a write lock is
+exclusive.
+Normally a write lock is only acquired when unmounting.
+.Pp
+The
+.Fn vfs_busy
+function locks the mount point pointed to by
+.Fa mp ,
+where
+.Fa flags
+describes the type of lock to acquire and whether or not to wait for a
+conflicting lock to be released.
+The following flags are available:
+.Pp
+.Bl -tag -width "VB_NOWAITXX" -offset indent -compact
+.It VB_READ
+Acquire a read lock.
+.It VB_WRITE
+Acquire a write lock.
+.It VB_NOWAIT
+Return immediately; do not wait for the conflicting lock to be released.
+.It VB_WAIT
+Wait for the conflicting lock to be released.
+.El
+.Pp
+If a conflicting lock was encountered,
+.Fn vfs_busy
+returns an error.
+.Pp
+The
+.Fn vfs_isbusy
+function checks whether the given mount point is locked.
+.Pp
+.Fn vfs_unbusy
+unlocks the given mount point.
+.Pp
+The
+.Nm vfs_busy
+API is implemented in the file
+.Pa sys/kern/vfs_subr.c .
+.Sh SEE ALSO
+.Xr rwlock 9 ,
+.Xr vfs 9