1 files changed, 304 insertions, 0 deletions
diff --git a/static/openbsd/man9/vnsubr.9 b/static/openbsd/man9/vnsubr.9
new file mode 100644
index 00000000..5719e64d
--- /dev/null
+++ b/static/openbsd/man9/vnsubr.9
@@ -0,0 +1,304 @@
+.\"     $OpenBSD: vnsubr.9,v 1.16 2019/10/06 16:32:56 jmc 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.
+.\"
+.\" 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: October 6 2019 $
+.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_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 VOP_LOOKUP 9 .
+.Bl -tag -width Ds
+.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
+.Fn VOP_CLOSE
+and calls
+.Xr vput 9
+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.
+.Pp
+The
+.Fn vn_lock
+function must not be called when the vnode's reference count is
+zero.
+Instead, the
+.Xr vget 9
+function should be used.
+.Pp
+In addition to the
+.Fa flags
+accepted by
+.Xr VOP_LOCK 9 ,
+the
+.Dv LK_RETRY
+flag may be used.
+.Dv LK_RETRY
+causes
+.Fn vn_lock
+to return the vnode even if it has been reclaimed.
+It must not be used with
+.Dv LK_NOWAIT .
+.Pp
+The
+.Fn vn_lock
+function can sleep.
+.It Fn vn_marktext "vp"
+Common code to mark the vnode
+.Fa vp
+as being the text of a running process.
+.It Fn vn_open "ndp" "fmode" "cmode"
+Common code for vnode open operations.
+.Pp
+The pathname is described in the
+.Vt nameidata
+structure pointed to by the
+.Fa ndp
+argument.
+When initializing the nameidata structure for
+.Fn vn_open
+with
+.Xr NDINIT 9 ,
+the
+.Fa op
+must be specified as 0, and the
+.Fa flags
+may only be 0, or
+.Dv KERNELPATH .
+The lookup mode and flags are set internally
+by
+.Fn vn_open .
+.Pp
+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
+.Fa "rw" "vp" "base" "len" "offset"
+.Fa "segflg" "ioflg" "cred" "aresid" "p"
+.Fc
+.Xc
+Common code to package up an I/O request on a vnode into a
+.Vt uio
+and then perform the I/O.
+The argument
+.Fa rw
+specifies whether the I/O is a read
+.Pq Dv UIO_READ
+or write
+.Pq Dv 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
+.Vt uio
+parameters.
+For further information on these parameters, see
+.Xr uiomove 9 .
+.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 in which to store the stat information.
+The argument
+.Fa p
+is the calling process.
+.Fn vn_stat
+basically calls the vnode operation
+.Xr VOP_GETATTR 9
+and transfers the contents of a
+.Vt vattr
+structure into a
+.Vt 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,
+.Er ETXTBSY
+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 it 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
+.Dv LK_RETRY
+flag is not passed to
+.Fn vn_lock .
+.It Bq Er EBUSY
+The
+.Dv LK_NOWAIT
+flag was set and
+.Fn vn_lock
+would have slept.
+.El
+.Sh CODE REFERENCES
+This section describes places within the
+.Ox
+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 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, especially 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.