8c21bc6224
- Not enabled by default. Needs kernel option FFS_SNAPSHOT.
- Change parameters of ffs_blkfree.
- Let the copy-on-write functions return an error so spec_strategy
may fail if the copy-on-write fails.
- Change genfs_*lock*() to use vp->v_vnlock instead of &vp->v_lock.
- Add flag B_METAONLY to VOP_BALLOC to return indirect block buffer.
- Add a function ffs_checkfreefile needed for snapshot creation.
- Add special handling of snapshot files:
Snapshots may not be opened for writing and the attributes are read-only.
Use the mtime as the time this snapshot was taken.
Deny mtime updates for snapshot files.
- Add function transferlockers to transfer any waiting processes from
one lock to another.
- Add vfsop VFS_SNAPSHOT to take a snapshot and make it accessible through
a vnode.
- Add snapshot support to ls, fsck_ffs and dump.
Welcome to 2.0F.
Approved by: Jason R. Thorpe <thorpej@netbsd.org>
356 lines
10 KiB
Groff
356 lines
10 KiB
Groff
.\" $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_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_restorerecurse ,
|
|
.Nm vn_setrecurse ,
|
|
.Nm vn_open ,
|
|
.Nm vn_stat ,
|
|
.Nm vn_writechk ,
|
|
.Nm vn_start_write ,
|
|
.Nm vn_finished_write ,
|
|
.Nm vn_cow_establish ,
|
|
.Nm vn_cow_disestablish
|
|
.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" "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_markexec "struct vnode *vp"
|
|
.Ft void
|
|
.Fn vn_marktext "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_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_stat "struct vnode *vp" "struct stat *sb" "struct proc *p"
|
|
.Ft int
|
|
.Fn vn_writechk "struct vnode *vp"
|
|
.Ft int
|
|
.Fn vn_start_write "struct vnode *vp" "struct mount **mpp" "int flags"
|
|
.Ft void
|
|
.Fn vn_finished_write "struct mount *mp" "int flags"
|
|
.Ft int
|
|
.Fn vn_cow_establish "struct vnode *vp" "int (*func)(void *, struct buf *)" "void *cookie"
|
|
.Ft int
|
|
.Fn vn_cow_disestablish "struct vnode *vp" "int (*func)(void *, struct buf *)" "void *cookie"
|
|
.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" "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
|
|
.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" "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_marktext "vp"
|
|
Common code to mark the vnode
|
|
.Fa vp
|
|
as being the text 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 Fn vn_rdwr "rw" "vp" "base" "len" "offset" "segflg" "ioflg" "cred" "aresid" "p"
|
|
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_readdir "fp" "buf" "segflg" "count" "done" "p" "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 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_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 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_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.
|
|
.It Fn vn_start_write "vp" "mpp" "flags"
|
|
Prepare to start a file system write operation.
|
|
If the operation is permitted, bump the count of operations in progress and
|
|
proceed.
|
|
If a suspend request is in progress (see
|
|
.Xr vfs_write_suspend 9 ) ,
|
|
wait until the suspension is over
|
|
and proceed.
|
|
If
|
|
.Fa vp
|
|
is not
|
|
.Dv NULL ,
|
|
its mount point is assigned to
|
|
.Fa mpp .
|
|
If the
|
|
.Dv V_WAIT
|
|
flag is set,
|
|
.Fn vn_start_write
|
|
waits until the suspension is over.
|
|
Otherwise it returns
|
|
.Er EWOULDBLOCK .
|
|
If the
|
|
.Dv V_PCATCH
|
|
flag is set,
|
|
.Dv PCATCH
|
|
gets added to the
|
|
.Fn tsleep
|
|
flags.
|
|
If the
|
|
.Dv V_SLEEPONLY
|
|
flag is set, the operations count is not bumped.
|
|
If the
|
|
.Dv V_LOWER
|
|
flag is set, no further vnodes must be locked.
|
|
If it is not set, no vnodes must be already locked.
|
|
If the operation is permitted zero is returned, otherwise
|
|
.Er EWOULDBLOCK
|
|
is returned.
|
|
.It Fn vn_finished_write "mp" "flags"
|
|
A file system write operation has finished.
|
|
Adjust the count of operations in progress and return.
|
|
Only the
|
|
.Dv V_LOWER
|
|
flag is valid.
|
|
.It Fn vn_cow_establish "vp" "func" "cookie"
|
|
Establish a copy-on-write callback on spec vnode
|
|
.Fa vp .
|
|
.Fa func
|
|
will be called for every buffer written through the strategy routine of
|
|
.Fa vp .
|
|
.It Fn vn_cow_disestablish "vp" "func" "cookie"
|
|
Disestablish a copy-on-write callback registered with
|
|
.Fn vn_cow_establish .
|
|
.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 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 intro 9 ,
|
|
.Xr lock 9 ,
|
|
.Xr namei 9 ,
|
|
.Xr vattr 9 ,
|
|
.Xr vfs 9 ,
|
|
.Xr vnode 9 ,
|
|
.Xr vnodeops 9
|