355 lines
9.5 KiB
Groff
355 lines
9.5 KiB
Groff
.\" $NetBSD: vnsubr.9,v 1.48 2021/06/29 22:40:53 dholland 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 28, 2021
|
|
.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_bdev_open ,
|
|
.Nm vn_bdev_openpath ,
|
|
.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
|
|
.Fo vn_open
|
|
.Fa "struct vnode *at_dvp" "struct pathbuf *pb"
|
|
.Fa "int nmode" "int fmode" "int cmode"
|
|
.Fa "struct vnode **ret_vp" "bool *ret_domove" "int *ret_fd"
|
|
.Fc
|
|
.Ft int
|
|
.Fn vn_bdev_open "dev_t dev" "struct vnode **vpp" "struct lwp *l"
|
|
.Ft int
|
|
.Fn vn_bdev_openpath "struct pathbuf *pb" "struct vnode **vpp" "struct lwp *l"
|
|
.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 flags used to lock the vnode.
|
|
There are the following flags:
|
|
.Pp
|
|
.Bl -tag -offset indent -width LK_EXCLUSIVE -compact
|
|
.It LK_SHARED
|
|
shared lock
|
|
.It LK_EXCLUSIVE
|
|
exclusive lock
|
|
.It LK_NOWAIT
|
|
do not sleep to await lock
|
|
.It LK_RETRY
|
|
allow lock operation on dead vnode
|
|
.El
|
|
.Pp
|
|
If the operation is successful zero is returned, otherwise an
|
|
appropriate error code is returned.
|
|
.Pp
|
|
.Fn vn_lock
|
|
must not be called when the vnode's reference count is zero.
|
|
.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 "at_dvp" "pb" "nmode" "fmode" "cmode" "ret_vp" "ret_domove" "ret_fd"
|
|
Common code for vnode open operations.
|
|
The
|
|
.Fa at_dvp
|
|
argument, if not NULL, provides the directory relative paths start
|
|
from, as per
|
|
.Xr openat 2 .
|
|
The
|
|
.Fa pb
|
|
argument gives the pathname.
|
|
The arguments
|
|
.Fa nmode ,
|
|
.Fa fmode
|
|
and
|
|
.Fa cmode
|
|
specify additional
|
|
.Xr namei 9
|
|
flags, the
|
|
.Xr open 2
|
|
flags (converted to
|
|
.Dv F*
|
|
from
|
|
.Dv O_*
|
|
form)
|
|
and the access mode (permissions) for creation, respectively.
|
|
The
|
|
.Fa nmode
|
|
argument is restricted to one or perhaps both of the flags
|
|
.Dv TRYEMULROOT
|
|
and
|
|
.Dv NOCHROOT .
|
|
Other
|
|
.Xr name 9
|
|
modes should be selected via
|
|
.Fn fmode .
|
|
The
|
|
.Fa ret_vp ,
|
|
.Fa ret_domove ,
|
|
and
|
|
.Fa ret_fd
|
|
arguments encode the possible return values.
|
|
When called,
|
|
.Fn vn_open
|
|
checks permissions and invokes the
|
|
.Xr VOP_OPEN 9
|
|
or
|
|
.Xr VOP_CREATE 9
|
|
vnode operations.
|
|
If the operation is unsuccessful an appropriate error code is returned.
|
|
Otherwise, zero is returned.
|
|
If a vnode is produced, it is returned locked via
|
|
.Fa ret_vp .
|
|
If a file descriptor number is produced instead, the pointer passed via
|
|
.Fa ret_vp
|
|
is NULL, the file descriptor is returned via
|
|
.Fa ret_fd ,
|
|
and the
|
|
.Fa ret_domove
|
|
returns a value that is true if the file descriptor should be moved
|
|
rather than copied.
|
|
These cases correspond to the internal errors
|
|
.Dv EMOVEFD
|
|
and
|
|
.Dv EDUPFD
|
|
respectively.
|
|
See
|
|
.Xr errno 9
|
|
for further information.
|
|
Callers unprepared to handle file descriptors can set
|
|
.Fa ret_fd
|
|
and
|
|
.Fa ret_domove
|
|
to NULL, in which case an operation that would produce a file descriptor
|
|
will instead fail with
|
|
.Dv EOPNOTSUPP .
|
|
.It Fn vn_bdev_open "dev" "vpp" "l"
|
|
Opens a block device by its device number for reading and writing, and
|
|
stores the vnode pointer into
|
|
.Fa *vpp .
|
|
The argument
|
|
.Fa l
|
|
is the calling process.
|
|
The vnode can be closed and freed with
|
|
.Fa vn_close .
|
|
.It Fn vn_bdev_openpath "pb" "vpp" "l"
|
|
Works like
|
|
.Fn vn_bdev_open
|
|
but looks up a file system path
|
|
.Fa pb
|
|
to determine the device ID.
|
|
.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
|
|
.Dv ( UIO_READ )
|
|
or write
|
|
.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
|