378 lines
11 KiB
Groff
378 lines
11 KiB
Groff
.\" $NetBSD: vnsubr.9,v 1.5 2002/01/06 22:15:19 deberg 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 <sys/param.h>
|
|
.Fd #include <sys/lock.h>
|
|
.Fd #include <sys/vnode.h>
|
|
.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
|