diff options
Diffstat (limited to 'static/netbsd/man9/vnsubr.9')
| -rw-r--r-- | static/netbsd/man9/vnsubr.9 | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/static/netbsd/man9/vnsubr.9 b/static/netbsd/man9/vnsubr.9 new file mode 100644 index 00000000..36d27a05 --- /dev/null +++ b/static/netbsd/man9/vnsubr.9 @@ -0,0 +1,354 @@ +.\" $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 |