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 n sys/param.h n sys/lock.h n 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 l -tag -width compact t Fn vn_bwrite "ap" Common code for block write operations. t 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. t 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. t 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. t 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:
p l -tag -offset indent -width LK_EXCLUSIVE -compact t LK_SHARED shared lock t LK_EXCLUSIVE exclusive lock t LK_NOWAIT do not sleep to await lock t LK_RETRY allow lock operation on dead vnode .El
p If the operation is successful zero is returned, otherwise an appropriate error code is returned.
p .Fn vn_lock must not be called when the vnode's reference count is zero. t Fn vn_markexec "vp" Common code to mark the vnode .Fa vp as containing executable code of a running process. t Fn vn_marktext "vp" Common code to mark the vnode .Fa vp as being the text of a running process. t 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 . t 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 . t 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. t 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 . t 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. t 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. t 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 l -tag -width Er t Bq Er EBUSY The LK_NOWAIT flag was set and .Fn vn_lock would have slept. t 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 . t 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
a sys/kern/vfs_vnops.c and
a 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
Indexes created Sat Sep 20 22:09:52 GMT 2025