April 9, 2008 VNSUBR 9

### NAME

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

### SYNOPSIS

```int` vn_bwrite(```void *ap`)
```int` vn_close(```struct vnode *vp``, int flags``, kauth_cred_t cred`)
```int` vn_default_error(```void *v`)
```int` vn_isunder(```struct vnode *dvp``, struct vnode *rvp``, struct lwp *l`)
```int` vn_lock(```struct vnode *vp``, int flags`)
```void` vn_markexec(```struct vnode *vp`)
```void` vn_marktext(```struct vnode *vp`)
```u_int` vn_setrecurse(```struct vnode *vp`)
```void` vn_restorerecurse(```struct vnode *vp``, u_int flags`)
```int` vn_open(```struct nameidata *ndp``, int fmode``, int cmode`)
```int` 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` )
```int` vn_readdir(```file_t *fp``, char *buf``, int segflg``, u_int count``, int *done``, struct lwp *l``, off_t **cookies``, int *ncookies`)
```int` vn_stat(```struct vnode *vp``, struct stat *sb``, struct lwp *l`)
```int` vn_writechk(```struct vnode *vp`)

### DESCRIPTION

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

### FUNCTIONS

vn_bwrite(```ap`)
  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 returned.

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.

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 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 v_interlock is released on return.

  vn_lock(``) must not be called when the vnode's reference count is zero. Instead, vget(9) should be used.

vn_markexec(```vp`)
  Common code to mark the vnode ```vp` as containing executable code of a running process.

vn_marktext(```vp`)
  Common code to mark the vnode ```vp` as being the text of a running process.

vn_setrecurse(```vp`)
  Common code to enable LK_CANRECURSE on the vnode lock for vnode ```vp`. vn_setrecurse(``) returns the new lockmgr(9) flags after the update.

vn_restorerecurse(```vp``, flags`)
  Common code to restore the vnode lock flags for the vnode ```vp`. It is called when done with vn_setrecurse(``).

vn_open(```ndp``, fmode``, cmode`)
  Common code for vnode open operations. The pathname is described in the nameidata pointer (see namei(9)). The arguments ```fmode` and ```cmode` specify the open(2) file mode and the access permissions for creation. vn_open(``) checks permissions and invokes the VOP_OPEN(9) or VOP_CREATE(9) vnode operations. If the operation is successful zero is returned, otherwise an appropriate error code is returned.

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 unlocked vnode is specified by ```vp`. The arguments ```l` and ```cred` are the calling lwp and its credentials. 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 is 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``, l`)
  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. The argument ```l` is the calling lwp. 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.

vn_writechk(```vp`)
  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.

### ERRORS

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

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

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

### CODE REFERENCES

This section describes places within the NetBSD source tree where actual code implementing or using the vnode framework can be found. All pathnames are relative to ```/usr/src`.

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

### SEE ALSO

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