.\"     $OpenBSD: vnsubr.9,v 1.6 2007/05/05 12:57:06 art 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" "struct proc *p"
.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" "p"
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
.Xr vget 9
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 or on 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.
.Fn vn_lock
releases the vnode interlock before exit.
.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.
The pathname is described in the
.Vt 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
.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 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, 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.