man/man9/vnsubr.9

.\"     $NetBSD: vnsubr.9,v 1.6 2002/02/13 08:18:56 ross 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 October 22, 2001
.Dt VNSUBR 9
.Os
.Sh NAME
.Nm vnsubr ,
.Nm vn_bwrite ,
.Nm vn_close ,
.Nm vn_closefile ,
.Nm vn_default_error ,
.Nm vn_fcntl ,
.Nm vn_ioctl ,
.Nm vn_isunder ,
.Nm vn_lock ,
.Nm vn_markexec ,
.Nm vn_setrecurse ,
.Nm vn_restorerecurse ,
.Nm vn_open ,
.Nm vn_read ,
.Nm vn_poll ,
.Nm vn_stat ,
.Nm vn_write ,
.Nm vn_writechk
.Nd high-level convenience functions for vnode operations
.Sh SYNOPSIS
.Fd #include \*[Lt]sys/param.h\*[Gt]
.Fd #include \*[Lt]sys/lock.h\*[Gt]
.Fd #include \*[Lt]sys/vnode.h\*[Gt]
.Ft int
.Fn vn_bwrite "void *ap"
.Ft int
.Fn vn_close "struct vnode *vp" "int flags" "struct ucred *cred" "struct proc *p"
.Ft int
.Fn vn_closefile "struct file *fp" "struct proc *p"
.Ft int
.Fn vn_default_error "void *v"
.Ft int
.Fn vn_fcntl "struct file *fp" "u_int com" "caddr_t data" "struct proc *p"
.Ft int
.Fn vn_ioctl "struct file *fp" "u_long com" "caddr_t data" "struct proc *p"
.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_markexec "struct vnode *vp"
.Ft u_int
.Fn vn_setrecurse "struct vnode *vp"
.Ft void
.Fn vn_restorerecurse "struct vnode *vp" "u_int flags"
.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_read "struct file *fp" "off_t *offset" "struct uio *uio" "struct ucred *cred" "int flags"
.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_poll "struct file *fp" "int events" "struct proc *p"
.Ft int
.Fn vn_stat "void *fdata" "struct stat *sb" "struct proc *p"
.Ft int
.Fn vn_write "struct file *fp" "off_t *offset" "struct uio *uio" "struct ucred *cred" "int flags"
.Ft int
.Fn vn_writechk "struct vnode *vp"
.Sh DESCRIPTION
The high-level functions described in this page are convenience
functions for simplied access to the vnode operations described in
.Xr vnodeops 9 .
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn vn_bwrite "ap"
Common code for block write operations.
.It Fn vn_close "vp" "flags" "cred" "p"
Common code for a vnode close.  The argument
.Fa vp
is the locked 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_closefile "fp" "p"
Common code for a file table vnode close operation.  The file is
described by
.Fa fp
and
.Fa p
is the calling process.
.Fn vn_closefile
simply calls
.Fn vn_close
with the appropriate arguments.
.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_fcntl "fp" "com" "data" "p"
Common code for a file table vnode
.Xr fcntl 2
operation.  The file is
specified by
.Fa fp .
The argument
.Fa p
is the calling process.
.Fn vn_fcntl
simply locks the vnode and invokes the vnode operation
.Xr VOP_FCNTL 9
with the command
.Fa com
and buffer
.Fa data .
The vnode is unlocked on return.  If the operation is successful zero
is returned, otherwise an appropriate error is returned.
.It Fn vn_ioctl "fp" "com" "data" "p"
Common code for a file table vnode ioctl operation.  The file is
specified by
.Fa fp .
The argument
.Fa p
is the calling process.
.Fn vn_ioctl
simply locks the vnode and invokes the vnode operation
.Xr VOP_IOCTL 9
with the command
.Fa com
and buffer
.Fa data .
The vnode is unlocked on return.  If the operation is successful zero
is returned, otherwise an appropriate error is returned.
.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"
Common code to acquire the lock for vnode
.Fa vp .
The argument
.Fa flags
specifies the
.Xr lockmgr 9
flags used to lock the vnode.  If the operation is successful zero is
returned, otherwise an appropriate error code is returned.  The vnode
interlock
.Em v_interlock
is releases on return.
.Pp
.Fn vn_lock
must not be called when the vnode's reference count is zero.  Instead,
.Xr vget 9
should be used.
.It Fn vn_markexec "vp"
Common code to mark the vnode
.Fa vp
as containing executable code of a running process.
.It Fn vn_setrecurse "vp"
Common code to enable LK_CANRECURSE on the vnode lock for vnode
.Fa vp .
.Fn vn_setrecurse
returns the new
.Xr lockmgr 9
flags after the update.
.It Fn vn_restorerecurse "vp" "flags"
Common code to restore the vnode lock flags for the vnode
.Fa vp .
It is called when done with
.Fn vn_setrecurse .
.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 Fo vn_rdwr
.Fa "rw" "vp" "base" "len" "offset" "segflg" "ioflg"
.Fa "cred" "aresid" "p"
.Fc
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 Fn vn_read "fp" "offset" "uio" "cred" "flags"
Common code for a file table vnode read.  The argument
.Fa fp
is the file structure,  The argument
.Fa offset
is the offset into the file.  The argument
.Fa uio
is the uio structure describing the memory to read into.  The caller's
credentials are specified in
.Fa cred .
The
.Fa flags
argument can define FOF_UPDATE_OFFSET to update the read position in
the file.  If the operation is successful zero is returned, otherwise
an appropriate error is returned.
.It Fo vn_readdir
.Fa "fp" "buf" "segflg" "count" "done" "p" "cookies"
.Fa "ncookies"
.Fc
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_poll "fp" "events" "p"
Common code for a file table vnode poll operation.
.Fn vn_poll
simply calls
.Xr VOP_POLL 9
with the events
.Fa events
and the calling process
.Fa p .
If the operation is success zero is returned, otherwise an appropriate
error code is returned.
.It Fn vn_stat "fdata" "sb" "p"
Common code for a vnode stat operation.  The vnode is specified by the
argument
.Fa fdata
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_write "fp" "offset" "uio" "cred" "flags"
Common code for a file table vnode write.  The argument
.Fa fp
is the file structure,  The argument
.Fa offset
is the offset into the file.  The argument
.Fa uio
is the uio structure describing the memory to read from.  The caller's
credentials are specified in
.Fa cred .
The
.Fa flags
argument can define FOF_UPDATE_OFFSET to update the read position in
the file.  If the operation is successful zero is returned, otherwise
an appropriate error 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.
.El
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or utilising the vnode
framework can be found.  All pathnames are relative to
.Pa /usr/src .
.Pp
The high-level convenience functions are implemented within the file
.Pa sys/kern/vfs_vnops.c .
.Sh SEE ALSO
.Xr intro 9 ,
.Xr lock 9 ,
.Xr namei 9 ,
.Xr vattr 9 ,
.Xr vfs 9 ,
.Xr vnode 9 ,
.Xr vnodeops 9