add vnsubr(9) from NetBSD. add the more detailed vn_lock(9) text to it

and remove vn_lock.

ok tedu@

3 files changed, 326 insertions, 130 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 12a491361c4..dc029aa9fd5 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.92 2005/05/10 04:38:45 msf Exp $
+#	$OpenBSD: Makefile,v 1.93 2005/05/27 22:31:47 marius Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -25,8 +25,8 @@ MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \
 	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 \
 	vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \
 	vflushbuf.9 vget.9 vgone.9 vhold.9 vinvalbuf.9 vput.9 vref.9 \
-	vrele.9 vnode.9 VOP_LOOKUP.9 vn_lock.9 vrecycle.9 vwaitforio.9 \
-	vwakeup.9 wdog_register.9
+	vrele.9 vnode.9 VOP_LOOKUP.9 vrecycle.9 vnsubr.9 vwaitforio.9 \
+	vwakeup.9 wdog_register.9 vnsubr.9
 
 MLINKS+=autoconf.9 config_init.9 autoconf.9 config_search.9 \
 	autoconf.9 config_rootsearch.9 autoconf.9 config_found_sm.9 \
@@ -282,6 +282,11 @@ 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+=vnsubr.9 vn_close.9 vnsubr.9 vn_default_error.9 vnsubr.9 vn_isunder.9 \
+	vnsubr.9 vn_lock.9 vnsubr.9 vn_open.9 vnsubr.9 vn_rdrw.9 \
+	vnsubr.9 vn_readdir.9 vnsubr.9 vn_stat.9 vnsubr.9 vn_writechk.9 \
+	vnsubr.9 vn_marktext.9
+
 # VOP functions
 MLINKS+=VOP_LOOKUP.9 VOP_CREATE.9 VOP_LOOKUP.9 VOP_FSYNC.9 \
 	VOP_LOOKUP.9 VOP_GETEXTATTR.9 VOP_LOOKUP.9 VOP_ISLOCKED.9 \
@@ -294,4 +299,4 @@ MLINKS+=VOP_LOOKUP.9 VOP_CREATE.9 VOP_LOOKUP.9 VOP_FSYNC.9 \
 	VOP_LOOKUP.9 VOP_SYMLINK.9 VOP_LOOKUP.9 VOP_UNLOCK.9 \
 	VOP_LOOKUP.9 VOP_WHITEOUT.9
 
-.include <bsd.prog.mk>
+.include <bsd.prog.mk>
\ No newline at end of file
diff --git a/share/man/man9/vn_lock.9 b/share/man/man9/vn_lock.9
deleted file mode 100644
index 919dfbeded2..00000000000
--- a/share/man/man9/vn_lock.9
+++ /dev/null
@@ -1,126 +0,0 @@
-.\"     $OpenBSD: vn_lock.9,v 1.7 2004/04/17 20:30:41 jmc 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
-.Pa 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
-argument 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
-.Dv 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
-.Dv LK_RETRY
-flag is not passed.
-.It Bq Er EBUSY
-The
-.Dv LK_NOWAIT
-flag was set and
-.Fn 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
-than 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
-.Dv LK_NOWAIT
-flag does prevent the caller from sleeping.
-.Pp
-The locking discipline as it relates to shared locks has yet to be defined.
diff --git a/share/man/man9/vnsubr.9 b/share/man/man9/vnsubr.9
new file mode 100644
index 00000000000..f071710fa14
--- /dev/null
+++ b/share/man/man9/vnsubr.9
@@ -0,0 +1,317 @@
+.\"     $OpenBSD: vnsubr.9,v 1.1 2005/05/27 22:31:47 marius Exp $
+.\"     $NetBSD: vnsubr.9,v 1.21 2004/05/25 14:54:56 hannken Exp $
+.\"
+.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Gregory McGarry.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" 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 May 25, 2004
+.Dt VNSUBR 9
+.Os
+.Sh NAME
+.Nm vnsubr ,
+.Nm vn_close ,
+.Nm vn_default_error ,
+.Nm vn_isunder ,
+.Nm vn_lock ,
+.Nm vn_marktext ,
+.Nm vn_rdwr ,
+.Nm vn_open ,
+.Nm vn_stat ,
+.Nm vn_writechk ,
+.Nd high-level convenience functions for vnode operations
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/lock.h
+.In sys/vnode.h
+.Ft int
+.Fn vn_close "struct vnode *vp" "int flags" "struct ucred *cred" "struct proc *p"
+.Ft int
+.Fn vn_default_error "void *v"
+.Ft int
+.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct proc *p"
+.Ft int
+.Fn vn_lock "struct vnode *vp" "int flags"
+.Ft void
+.Fn vn_marktext "struct vnode *vp"
+.Ft int
+.Fn vn_open "struct nameidata *ndp" "int fmode" "int cmode"
+.Ft int
+.Fo vn_rdwr
+.Fa "enum uio_rw rw" "struct vnode *vp" "caddr_t base"
+.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg"
+.Fa "struct ucred *cred" "size_t *aresid" "struct proc *p"
+.Fc
+.Ft int
+.Fn vn_readdir "struct file *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct proc *p" "off_t **cookies" "int *ncookies"
+.Ft int
+.Fn vn_stat "struct vnode *vp" "struct stat *sb" "struct proc *p"
+.Ft int
+.Fn vn_writechk "struct vnode *vp"
+.Sh DESCRIPTION
+The high-level functions described in this page are convenience
+functions for simplified access to the vnode operations described in
+.Xr vnodeops 9 .
+.Sh FUNCTIONS
+.Bl -tag -width Ds -compact
+.It Fn vn_close "vp" "flags" "cred" "p"
+Common code for a vnode close.
+The argument
+.Fa vp
+is the unlocked vnode of the vnode to close.
+.Fn vn_close
+simply locks the vnode, invokes the vnode operation
+.Xr VOP_CLOSE 9
+and calls
+.Fn vput
+to return the vnode to the freelist or holdlist.
+Note that
+.Fn vn_close
+expects an unlocked, referenced vnode and will dereference the vnode
+prior to returning.
+If the operation is successful zero is returned,
+otherwise an appropriate error is returned.
+.It Fn vn_default_error "v"
+A generic "default" routine that just returns error.
+It is used by a file system to specify unsupported operations in
+the vnode operations vector.
+.It Fn vn_isunder "dvp" "rvp" "p"
+Common code to check if one directory specified by the vnode
+.Fa rvp
+can be found inside the directory specified by the vnode
+.Fa dvp .
+The argument
+.Fa p
+is the calling process.
+.Fn vn_isunder
+is intended to be used in
+.Xr chroot 2 ,
+.Xr chdir 2 ,
+.Xr fchdir 2 ,
+etc., to ensure that
+.Xr chroot 2
+actually means something.
+If the operation is successful zero is returned, otherwise 1 is returned.
+.It Fn vn_lock "vp" "flags"
+Acquire the vnode lock.  Certain file system operations require that
+the vnode lock be held when they are called.
+See
+.Pa 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
+argument 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
+.Dv 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.
+.It Fn vn_open "ndp" "fmode" "cmode"
+Common code for vnode open operations.
+The pathname is described in the nameidata pointer (see
+.Xr namei 9 ) .
+The arguments
+.Fa fmode
+and
+.Fa cmode
+specify the
+.Xr open 2
+file mode and the access permissions for creation.
+.Fn vn_open
+checks  permissions and invokes the
+.Xr VOP_OPEN 9
+or
+.Xr VOP_CREATE 9
+vnode operations.
+If the operation is successful zero is returned,
+otherwise an appropriate error code is returned.
+.It Xo Fo vn_rdwr "enum uio_rw rw" "struct vnode *vp" "caddr_t base"
+.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg"
+.Fa "struct ucred *cred" "size_t *aresid" "struct proc *p"
+.Fc
+.Xc
+Common code to package up an I/O request on a vnode into a uio and
+then perform the I/O.
+The argument
+.Fa rw
+specifies whether the I/O is a read (UIO_READ) or write (UIO_WRITE)
+operation.
+The unlocked vnode is specified by
+.Fa vp .
+The arguments
+.Fa p
+and
+.Fa cred
+are the calling process and its credentials.
+The remaining arguments specify the uio parameters.
+For further information on these parameters see
+.Xr uiomove 9 .
+.It Xo Fo vn_readdir "struct file *fp" "char *buf" "int segflg" 
+.Fa "u_int count" "int *done" "struct proc *p" 
+.Fa "off_t **cookies" "int *ncookies"
+.Fc
+.Xc
+Common code for reading the contents of a directory.
+The argument
+.Fa fp
+is the file structure,
+.Fa buf
+is the buffer for placing the struct dirent structures.
+The arguments
+.Fa cookies
+and
+.Fa ncookies
+specify the addresses for the list and number of directory seek
+cookies generated for NFS.
+Both
+.Fa cookies
+and
+.Fa ncookies
+should be NULL is they aren't required to be returned by
+.Fn vn_readdir .
+If the operation is successful zero is returned, otherwise an
+appropriate error code is returned.
+.It Fn vn_stat "vp" "sb" "p"
+Common code for a vnode stat operation.
+The vnode is specified by the argument
+.Fa vp
+and
+.Fa sb
+is the buffer to return the stat information.
+The argument
+.Fa p
+is the calling process.
+.Fn vn_stat
+basically calls the vnode operation
+.Xr VOP_GETATTR 9
+and transfer the contents of a vattr structure into a struct stat.
+If the operation is successful zero is returned, otherwise an
+appropriate error code is returned.
+.It Fn vn_writechk "vp"
+Common code to check for write permission on the vnode
+.Fa vp .
+A vnode is read-only if it is in use as a process's text image.
+If the vnode is read-only ETEXTBSY is returned, otherwise zero is
+returned to indicate that the vnode can be written to.
+.El
+.Sh ERRORS
+.Bl -tag -width Er
+.It Bq Er ETXTBSY
+Cannot write to a vnode since is a process's text image.
+.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 to
+.Fn vn_lock .
+.It Bq Er EBUSY
+The LK_NOWAIT flag was set and
+.Fn vn_lock
+would have slept.
+.It Fn vn_marktext "vp"
+Common code to mark the vnode
+.Fa vp
+as being the text of a running process.
+.El
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where actual code implementing or using the vnode
+framework can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The high-level convenience functions are implemented within the files
+.Pa sys/kern/vfs_vnops.c
+and
+.Pa sys/sys/vnode.h .
+.Sh SEE ALSO
+.Xr file 9 ,
+.Xr intro 9 ,
+.Xr lock 9 ,
+.Xr namei 9 ,
+.Xr vfs 9 ,
+.Xr vnode 9 ,
+.Xr VOP_LOOKUP 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
+than 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
+.Dv LK_NOWAIT
+flag does prevent the caller from sleeping.
+.Pp
+The locking discipline as it relates to shared locks has yet to be defined.