Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

VNSUBR(9)                  Kernel Developer's Manual                 VNSUBR(9)

     vnsubr, vn_bwrite, vn_close, vn_default_error, vn_isunder, vn_lock,
     vn_markexec, vn_marktext, vn_rdwr, vn_open, vn_bdev_open,
     vn_bdev_openpath, vn_stat, vn_writechk - high-level convenience functions
     for vnode operations

     #include <sys/param.h>
     #include <sys/lock.h>
     #include <sys/vnode.h>

     vn_bwrite(void *ap);

     vn_close(struct vnode *vp, int flags, kauth_cred_t cred);

     vn_default_error(void *v);

     vn_isunder(struct vnode *dvp, struct vnode *rvp, struct lwp *l);

     vn_lock(struct vnode *vp, int flags);

     vn_markexec(struct vnode *vp);

     vn_marktext(struct vnode *vp);

     vn_open(struct vnode *at_dvp, struct pathbuf *pb, int nmode, int fmode,
         int cmode, struct vnode **ret_vp, bool *ret_domove, int *ret_fd);

     vn_bdev_open(dev_t dev, struct vnode **vpp, struct lwp *l);

     vn_bdev_openpath(struct pathbuf *pb, struct vnode **vpp, struct lwp *l);

     vn_rdwr(enum uio_rw rw, struct vnode *vp, void *base, int len,
         off_t offset, enum uio_seg segflg, int ioflg, kauth_cred_t cred,
         size_t *aresid, struct lwp *l);

     vn_readdir(file_t *fp, char *buf, int segflg, u_int count, int *done,
         struct lwp *l, off_t **cookies, int *ncookies);

     vn_stat(struct vnode *vp, struct stat *sb);

     vn_writechk(struct vnode *vp);

     The high-level functions described in this page are convenience functions
     for simplified access to the vnode operations described in vnodeops(9).

              Common code for block write operations.

     vn_close(vp, flags, cred)
              Common code for a vnode close.  The argument vp is the unlocked
              vnode of the vnode to close.  vn_close() simply locks the vnode,
              invokes the vnode operation VOP_CLOSE(9) and calls vput() to
              return the vnode to the freelist or holdlist.  Note that
              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

              A generic "default" routine that just returns error.  It is used
              by a file system to specify unsupported operations in the vnode
              operations vector.

     vn_isunder(dvp, rvp, l)
              Common code to check if one directory specified by the vnode rvp
              can be found inside the directory specified by the vnode dvp.
              The argument l is the calling process.  vn_isunder() is intended
              to be used in chroot(2), chdir(2), fchdir(2), etc., to ensure
              that chroot(2) actually means something.  If the operation is
              successful zero is returned, otherwise 1 is returned.

     vn_lock(vp, flags)
              Common code to acquire the lock for vnode vp.  The argument
              flags specifies the flags used to lock the vnode.  There are the
              following flags:

                    LK_SHARED     shared lock
                    LK_EXCLUSIVE  exclusive lock
                    LK_NOWAIT     do not sleep to await lock
                    LK_RETRY      allow lock operation on dead vnode

              If the operation is successful zero is returned, otherwise an
              appropriate error code is returned.

              vn_lock() must not be called when the vnode's reference count is

              Common code to mark the vnode vp as containing executable code
              of a running process.

              Common code to mark the vnode vp as being the text of a running

     vn_open(at_dvp, pb, nmode, fmode, cmode, ret_vp, ret_domove, ret_fd)
              Common code for vnode open operations.  The at_dvp argument, if
              not NULL, provides the directory relative paths start from, as
              per openat(2).  The pb argument gives the pathname.  The
              arguments nmode, fmode and cmode specify additional namei(9)
              flags, the open(2) flags (converted to F* from O_* form) and the
              access mode (permissions) for creation, respectively.  The nmode
              argument is restricted to one or perhaps both of the flags
              TRYEMULROOT and NOCHROOT.  Other name(9) modes should be
              selected via fmode().  The ret_vp, ret_domove, and ret_fd
              arguments encode the possible return values.  When called,
              vn_open() checks permissions and invokes the VOP_OPEN(9) or
              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 ret_vp.  If a file descriptor number is produced instead,
              the pointer passed via ret_vp is NULL, the file descriptor is
              returned via ret_fd, and the 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 EMOVEFD and EDUPFD
              respectively.  See errno(9) for further information.  Callers
              unprepared to handle file descriptors can set ret_fd and
              ret_domove to NULL, in which case an operation that would
              produce a file descriptor will instead fail with EOPNOTSUPP.

     vn_bdev_open(dev, vpp, l)
              Opens a block device by its device number for reading and
              writing, and stores the vnode pointer into *vpp.  The argument l
              is the calling process.  The vnode can be closed and freed with

     vn_bdev_openpath(pb, vpp, l)
              Works like vn_bdev_open() but looks up a file system path pb to
              determine the device ID.

     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 rw specifies whether the
              I/O is a read (UIO_READ) or write (UIO_WRITE) operation.  The
              vnode is specified by vp.  The arguments l and cred are the
              calling lwp and its credentials.  If ioflg contains
              IO_NODELOCKED, it is expected that the vnode is locked.  ioflg
              will be passed to VOP_READ()/VOP_WRITE().  The remaining
              arguments specify the uio parameters.  For further information
              on these parameters see uiomove(9).

     vn_readdir(fp, buf, segflg, count, done, l, cookies, ncookies)
              Common code for reading the contents of a directory.  The
              argument fp is the file structure, buf is the buffer for placing
              the struct dirent structures.  The arguments cookies and
              ncookies specify the addresses for the list and number of
              directory seek cookies generated for NFS.  Both cookies and
              ncookies should be NULL if they aren't required to be returned
              by vn_readdir().  If the operation is successful zero is
              returned, otherwise an appropriate error code is returned.

     vn_stat(vp, sb)
              Common code for a vnode stat operation.  The vnode is specified
              by the argument vp, and sb is the buffer to return the stat
              information.  vn_stat() basically calls the vnode operation
              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.

              Common code to check for write permission on the vnode 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.

     [EBUSY]            The LK_NOWAIT flag was set and vn_lock() would have

     [ENOENT]           The vnode has been reclaimed and is dead.  This error
                        is only returned if the LK_RETRY flag is not passed to

     [ETXTBSY]          Cannot write to a vnode since is a process's text

     The high-level convenience functions are implemented within the files
     sys/kern/vfs_vnops.c and sys/sys/vnode.h.

     file(9), intro(9), lock(9), namei(9), vattr(9), vfs(9), vnode(9),

NetBSD 10.99                     June 28, 2021                    NetBSD 10.99