269 lines
7.6 KiB
Groff
269 lines
7.6 KiB
Groff
.\" $NetBSD: vnsubr.9,v 1.40 2010/12/02 12:54:13 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001, 2005, 2006 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 June 18, 2010
|
|
.Dt VNSUBR 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm vnsubr ,
|
|
.Nm vn_bwrite ,
|
|
.Nm vn_close ,
|
|
.Nm vn_default_error ,
|
|
.Nm vn_isunder ,
|
|
.Nm vn_lock ,
|
|
.Nm vn_markexec ,
|
|
.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_bwrite "void *ap"
|
|
.Ft int
|
|
.Fn vn_close "struct vnode *vp" "int flags" "kauth_cred_t cred"
|
|
.Ft int
|
|
.Fn vn_default_error "void *v"
|
|
.Ft int
|
|
.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct lwp *l"
|
|
.Ft int
|
|
.Fn vn_lock "struct vnode *vp" "int flags"
|
|
.Ft void
|
|
.Fn vn_markexec "struct vnode *vp"
|
|
.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" "void *base"
|
|
.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg"
|
|
.Fa "kauth_cred_t cred" "size_t *aresid" "struct lwp *l"
|
|
.Fc
|
|
.Ft int
|
|
.Fn vn_readdir "file_t *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct lwp *l" "off_t **cookies" "int *ncookies"
|
|
.Ft int
|
|
.Fn vn_stat "struct vnode *vp" "struct stat *sb"
|
|
.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 compact
|
|
.It Fn vn_bwrite "ap"
|
|
Common code for block write operations.
|
|
.It Fn vn_close "vp" "flags" "cred"
|
|
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" "l"
|
|
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 l
|
|
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 released 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_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 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 and the vnode is locked,
|
|
otherwise an appropriate error code is returned.
|
|
.It Fn vn_rdwr "rw" "vp" "base" "len" "offset" "segflg" "ioflg" "cred" "aresid" "l"
|
|
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
|
|
.Pq Dv UIO_READ
|
|
or write
|
|
.Pq Dv UIO_WRITE
|
|
operation.
|
|
The vnode is specified by
|
|
.Fa vp .
|
|
The arguments
|
|
.Fa l
|
|
and
|
|
.Fa cred
|
|
are the calling lwp and its credentials.
|
|
If
|
|
.Fa ioflg
|
|
contains
|
|
.Dv IO_NODELOCKED ,
|
|
it is expected that the vnode is locked.
|
|
.Fa ioflg
|
|
will be passed to
|
|
.Fn VOP_READ Ns No / Ns Fn VOP_WRITE .
|
|
The remaining arguments specify the uio parameters.
|
|
For further information on these parameters see
|
|
.Xr uiomove 9 .
|
|
.It Fn vn_readdir "fp" "buf" "segflg" "count" "done" "l" "cookies" "ncookies"
|
|
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
|
|
.Dv NULL
|
|
if 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"
|
|
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.
|
|
.Fn vn_stat
|
|
basically calls the vnode operation
|
|
.Xr VOP_GETATTR 9
|
|
and transfers 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 EBUSY
|
|
The LK_NOWAIT flag was set and
|
|
.Fn vn_lock
|
|
would have slept.
|
|
.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 ETXTBSY
|
|
Cannot write to a vnode since is a process's text image.
|
|
.El
|
|
.Sh CODE REFERENCES
|
|
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 vattr 9 ,
|
|
.Xr vfs 9 ,
|
|
.Xr vnode 9 ,
|
|
.Xr vnodeops 9
|