.\"     $NetBSD: vnode.9,v 1.84 2022/03/19 13:53:32 hannken 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 March 19, 2022
.Dt VNODE 9
.Os
.Sh NAME
.Nm vnode ,
.Nm vref ,
.Nm vrele ,
.Nm vrele_async ,
.Nm vput ,
.Nm vhold ,
.Nm holdrele ,
.Nm vcache_get ,
.Nm vcache_new ,
.Nm vcache_rekey_enter ,
.Nm vcache_rekey_exit ,
.Nm vrecycle ,
.Nm vgone ,
.Nm vgonel ,
.Nm vdead_check ,
.Nm vflush ,
.Nm bdevvp ,
.Nm cdevvp ,
.Nm vfinddev ,
.Nm vdevgone ,
.Nm vwakeup ,
.Nm vflushbuf ,
.Nm vinvalbuf ,
.Nm vtruncbuf ,
.Nm vprint
.Nd kernel representation of a file or directory
.Sh SYNOPSIS
.In sys/param.h
.In sys/vnode.h
.Ft void
.Fn vref "struct vnode *vp"
.Ft void
.Fn vrele "struct vnode *vp"
.Ft void
.Fn vrele_async "struct vnode *vp"
.Ft void
.Fn vput "struct vnode *vp"
.Ft void
.Fn vhold "struct vnode *vp"
.Ft void
.Fn holdrele "struct vnode *vp"
.Ft int
.Fn vcache_get "struct mount *mp" "const void *key" "size_t key_len" "struct vnode **vpp"
.Ft int
.Fn vcache_new "struct mount *mp" "struct vnode *dvp" "struct vattr *vap" "kauth_cred_t cred" "void *extra" "struct vnode **vpp"
.Ft int
.Fn vcache_rekey_enter "struct mount *mp" "struct vnode *vp" "const void *old_key" "size_t old_key_len" "const void *new_key" "size_t new_key_len"
.Ft void
.Fn vcache_rekey_exit "struct mount *mp" "struct vnode *vp" "const void *old_key" "size_t old_key_len" "const void *new_key" "size_t new_key_len"
.Ft int
.Fn vrecycle "struct vnode *vp"
.Ft void
.Fn vgone "struct vnode *vp"
.Ft void
.Fn vgonel "struct vnode *vp" "struct lwp *l"
.Ft int
.Fn vdead_check "struct vnode *vp" "int flags"
.Ft int
.Fn vflush "struct mount *mp" "struct vnode *skipvp" "int flags"
.Ft int
.Fn bdevvp "dev_t dev" "struct vnode **vpp"
.Ft int
.Fn cdevvp "dev_t dev" "struct vnode **vpp"
.Ft int
.Fn vfinddev "dev_t dev" "enum vtype" "struct vnode **vpp"
.Ft void
.Fn vdevgone "int maj" "int minl" "int minh" "enum vtype type"
.Ft void
.Fn vwakeup "struct buf *bp"
.Ft int
.Fn vflushbuf "struct vnode *vp" "int sync"
.Ft int
.Fn vinvalbuf "struct vnode *vp" "int flags" "kauth_cred_t cred" "struct lwp *l" "int slpflag" "int slptimeo"
.Ft int
.Fn vtruncbuf "struct vnode *vp" "daddr_t lbn" "int slpflag" "int slptimeo"
.Ft void
.Fn vprint "const char *label" "struct vnode *vp"
.Sh DESCRIPTION
A
.Em vnode
represents an on-disk file in use by the system.
Each
.Xr vfs 9
file system provides a set of
.Xr vnodeops 9
operations on vnodes, invoked by file-system-independent system calls
and supported by file-system-independent library routines.
.Pp
Each mounted file system provides a vnode for the root of the file
system, via
.Xr VFS_ROOT 9 .
Other vnodes are obtained by
.Xr VOP_LOOKUP 9 .
Users of vnodes usually invoke these indirectly via
.Xr namei 9
to obtain vnodes from paths.
.Pp
Each file system usually maintains a cache mapping recently used inode
numbers, or the equivalent, to vnodes, and a cache mapping recently
used file names to vnodes.
If memory is scarce, the system may decide to
.Em reclaim
an unused cached vnode, calling
.Xr VOP_RECLAIM 9
to remove it from the caches and to free file-system-specific memory
associated with it.
A file system may also choose to immediately reclaim a cached vnode
once it is unused, in
.Xr VOP_INACTIVE 9 ,
if the vnode has been deleted on disk.
.Pp
When a file system retrieves a vnode from a cache, the vnode may not
have any users, and another thread in the system may be simultaneously
deciding to reclaim it.
Thus, to retrieve a vnode from a cache, one must use
.Fn vcache_get ,
not
.Fn vref ,
to acquire the first reference.
.Pp
The vnode has the following structure:
.Bd -literal
struct vnode {
	struct uvm_object v_uobj;		/* the VM object */
	kcondvar_t	v_cv;			/* synchronization */
	voff_t		v_size;			/* size of file */
	voff_t		v_writesize;		/* new size after write */
	int		v_iflag;		/* VI_* flags */
	int		v_vflag;		/* VV_* flags */
	int		v_uflag;		/* VU_* flags */
	int		v_numoutput;		/* # of pending writes */
	int		v_writecount;		/* ref count of writers */
	int		v_holdcnt;		/* page & buffer refs */
	struct mount	*v_mount;		/* ptr to vfs we are in */
	int		(**v_op)(void *);	/* vnode operations vector */
	struct buflists	v_cleanblkhd;		/* clean blocklist head */
	struct buflists	v_dirtyblkhd;		/* dirty blocklist head */
	union {
		struct mount	*vu_mountedhere;/* ptr to vfs (VDIR) */
		struct socket	*vu_socket;	/* unix ipc (VSOCK) */
		struct specnode	*vu_specnode;	/* device (VCHR, VBLK) */
		struct fifoinfo	*vu_fifoinfo;	/* fifo (VFIFO) */
		struct uvm_ractx *vu_ractx;	/* read-ahead ctx (VREG) */
	} v_un;
	enum vtype	v_type;			/* vnode type */
	enum vtagtype	v_tag;			/* type of underlying data */
	void 		*v_data;		/* private data for fs */
	struct klist	v_klist;		/* notes attached to vnode */
};
.Ed
.Pp
Most members of the vnode structure should be treated as opaque and
only manipulated using the proper functions.
There are some rather common exceptions detailed throughout this page.
.Pp
Files and file systems are inextricably linked with the virtual memory
system and
.Em v_uobj
contains the data maintained by the virtual memory system.
For compatibility with code written before the integration of
.Xr uvm 9
into
.Nx ,
C-preprocessor directives are used to alias the members of
.Em v_uobj .
.Pp
Vnode flags are recorded by
.Em v_iflag ,
.Em v_vflag
and
.Em v_uflag .
Valid flags are:
.Pp
.Bl -tag -offset indent -width ".Dv VI_WRMAPDIRTY" -compact
.It Dv VV_ROOT
This vnode is the root of its file system.
.It Dv VV_SYSTEM
This vnode is being used by the kernel; only used to skip quota files in
.Fn vflush .
.It Dv VV_ISTTY
This vnode represents a tty; used when reading dead vnodes.
.It Dv VV_MAPPED
This vnode might have user mappings.
.It Dv VV_MPSAFE
This file system is MP safe.
.It Dv VI_TEXT
This vnode is a pure text prototype.
.It Dv VI_EXECMAP
This vnode has executable mappings.
.It Dv VI_WRMAP
This vnode might have PROT_WRITE user mappings.
.It Dv VI_WRMAPDIRTY
This vnode might have dirty pages due to
.Dv VWRITEMAP .
.It Dv VI_XLOCK
This vnode is currently locked to change underlying type.
.It Dv VI_ONWORKLST
This vnode is on syncer work-list.
.It Dv VI_MARKER
A dummy marker vnode.
.It Dv VI_CLEAN
This vnode has been reclaimed and is no longer attached to a file system.
.It Dv VU_DIROP
This vnode is involved in a directory operation.
This flag is used exclusively by LFS.
.El
.Pp
The
.Dv VI_XLOCK
flag is used to prevent multiple processes from entering
the vnode reclamation code.
It is also used as a flag to indicate that reclamation is in progress.
Before
.Em v_iflag
can be modified, the
.Em v_interlock
mutex must be acquired.
See
.Xr lock 9
for details on the kernel locking API.
.Pp
Each vnode has three reference counts:
.Em v_usecount ,
.Em v_writecount
and
.Em v_holdcnt .
The first is the number of active references within the
kernel to the vnode.
This count is maintained by
.Fn vref ,
.Fn vrele ,
.Fn vrele_async ,
and
.Fn vput .
The second is the number of active references within the kernel to the
vnode performing write access to the file.
It is maintained by the
.Xr open 2
and
.Xr close 2
system calls.
The third is the number of references within the kernel
requiring the vnode to remain active and not be recycled.
This count is maintained by
.Fn vhold
and
.Fn holdrele .
When both the
.Em v_usecount
and
.Em v_holdcnt
reach zero, the vnode is cached.
The transition from the cache is handled by a kernel thread and
.Fn vrecycle .
Access to
.Em v_usecount ,
.Em v_writecount
and
.Em v_holdcnt
is also protected by the
.Em v_interlock
mutex.
.Pp
The number of pending synchronous and asynchronous writes on the
vnode are recorded in
.Em v_numoutput .
It is used by
.Xr fsync 2
to wait for all writes to complete before returning to the user.
Its value must only be modified at splbio (see
.Xr spl 9 ) .
It does not track the number of dirty buffers attached to the
vnode.
.Pp
The link to the file system which owns the vnode is recorded by
.Em v_mount .
See
.Xr vfsops 9
for further information of file system mount status.
.Pp
The
.Em v_op
pointer points to its vnode operations vector.
This vector describes what operations can be done to the file associated
with the vnode.
The system maintains one vnode operations vector for each file system
type configured into the kernel.
The vnode operations vector contains a pointer to a function for
each operation supported by the file system.
See
.Xr vnodeops 9
for a description of vnode operations.
.Pp
When a user wants a new vnode for another file or wants a valid vnode
which is cached,
.Fn vcache_get
or
.Fn vcache_new
is invoked to allocate a vnode and initialize it for the new file.
.Pp
The type of object the vnode represents is recorded by
.Em v_type .
It is used by generic code to perform checks to ensure operations are
performed on valid file system objects.
Valid types are:
.Pp
.Bl -tag -offset indent -width VFIFO -compact
.It Dv VNON
The vnode has no type.
.It Dv VREG
The vnode represents a regular file.
.It Dv VDIR
The vnode represents a directory.
.It Dv VBLK
The vnode represents a block special device.
.It Dv VCHR
The vnode represents a character special device.
.It Dv VLNK
The vnode represents a symbolic link.
.It Dv VSOCK
The vnode represents a socket.
.It Dv VFIFO
The vnode represents a pipe.
.It Dv VBAD
The vnode represents a bad file (not currently used).
.El
.Pp
Vnode tag types are used by external programs only (e.g.,
.Xr pstat 8 ) ,
and should never be inspected by the kernel.
Its use is deprecated
since new
.Em v_tag
values cannot be defined for loadable file systems.
The
.Em v_tag
member is read-only.
Valid tag types are:
.Pp
.Bl -tag -offset indent -width "VT_FILECORE " -compact
.It Dv VT_NON
non file system
.It Dv VT_UFS
universal file system
.It Dv VT_NFS
network file system
.It Dv VT_MFS
memory file system
.It Dv VT_MSDOSFS
FAT file system
.It Dv VT_LFS
log-structured file system
.It Dv VT_LOFS
loopback file system
.It Dv VT_FDESC
file descriptor file system
.It Dv VT_NULL
null file system layer
.It Dv VT_UMAP
uid/gid remapping file system layer
.It Dv VT_KERNFS
kernel interface file system
.It Dv VT_PROCFS
process interface file system
.It Dv VT_AFS
AFS file system
.It Dv VT_ISOFS
ISO 9660 file system(s)
.It Dv VT_UNION
union file system
.It Dv VT_ADOSFS
Amiga file system
.It Dv VT_EXT2FS
Linux's ext2 file system
.It Dv VT_CODA
Coda file system
.It Dv VT_FILECORE
filecore file system
.It Dv VT_NTFS
Microsoft NT's file system
.It Dv VT_VFS
virtual file system
.It Dv VT_OVERLAY
overlay file system
.It Dv VT_SMBFS
SMB file system
.It Dv VT_PTYFS
pseudo-terminal device file system
.It Dv VT_TMPFS
efficient memory file system
.It Dv VT_UDF
universal disk format file system
.It Dv VT_SYSVBFS
systemV boot file system
.El
.Pp
The vnode lock is acquired by calling
.Xr vn_lock 9
and released by calling
.Xr VOP_UNLOCK 9 .
The reason for this asymmetry is that
.Xr vn_lock 9
is a wrapper for
.Xr VOP_LOCK 9
with extra checks, while the unlocking step usually does not need
additional checks and thus has no wrapper.
.Pp
The vnode locking operation is complicated because it is used for many
purposes.
Sometimes it is used to bundle a series of vnode operations (see
.Xr vnodeops 9 )
into an atomic group.
Many file systems rely on it to prevent race conditions in updating
file system type specific data structures rather than using their
own private locks.
The vnode lock can operate as a multiple-reader (shared-access lock)
or single-writer lock (exclusive access lock), however many current file
system implementations were written assuming only single-writer
locking.
Multiple-reader locking functions equivalently only in the presence
of big-lock SMP locking or a uni-processor machine.
The lock may be held while sleeping.
While the vnode lock is acquired, the holder is guaranteed that the
vnode will not be reclaimed or invalidated.
Most file system functions require that you hold the vnode lock on entry.
See
.Xr lock 9
for details on the kernel locking API.
.Pp
Each file system underlying a vnode allocates its own private area and
hangs it from
.Em v_data .
.Pp
Most functions discussed in this page that operate on vnodes cannot be
called from interrupt context.
The members
.Em v_numoutput ,
.Em v_holdcnt ,
.Em v_dirtyblkhd ,
and
.Em v_cleanblkhd
are modified in interrupt context and must be protected by
.Xr splbio 9
unless it is certain that there is no chance an interrupt handler will
modify them.
The vnode lock must not be acquired within interrupt context.
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn vref "vp"
Increment
.Em v_usecount
of the vnode
.Em vp .
Any kernel thread system which uses a vnode (e.g., during the operation
of some algorithm or to store in a data structure) should call
.Fn vref .
.It Fn vrele "vp"
Decrement
.Em v_usecount
of unlocked vnode
.Em vp .
Any code in the system which is using a vnode should call
.Fn vrele
when it is finished with the vnode.
If
.Em v_usecount
of the vnode reaches zero and
.Em v_holdcnt
is greater than zero, the vnode is placed on the holdlist.
If both
.Em v_usecount
and
.Em v_holdcnt
are zero, the vnode is cached.
.It Fn vrele_async "vp"
Will asynchronously release the vnode in different context than the caller,
sometime after the call.
.It Fn vput "vp"
Legacy convenience routine for unlocking and releasing
.Fa vp .
Equivalent to:
.Bd -literal -offset abcd
.No "VOP_UNLOCK(" Ns Fa vp Ns Li ");"
.No "vrele(" Ns Fa vp Ns Li ");"
.Ed
.Pp
New code should prefer using
.Xr VOP_UNLOCK 9
and
.Fn vrele
directly.
.It Fn vhold "vp"
Mark the vnode
.Fa vp
as active by incrementing
.Em vp->v_holdcnt .
Once held, the vnode will not be recycled until it is
released with
.Fn holdrele .
.It Fn holdrele "vp"
Mark the vnode
.Fa vp
as inactive by decrementing
.Em vp->v_holdcnt .
.It Fn vcache_get "mp" "key" "key_len" "vpp"
Allocate a new vnode.
The new vnode is returned referenced in the address specified by
.Fa vpp .
.Pp
The argument
.Fa mp
is the mount point for the file system to lookup the file in.
.Pp
The arguments
.Fa key
and
.Fa key_len
uniquely identify the file in the file system.
.Pp
If a vnode is successfully retrieved zero is returned, otherwise an
appropriate error code is returned.
.It Fn vcache_new "mp" "dvp" "vap" "cred" "vpp"
Allocate a new vnode with a new file.
The new vnode is returned referenced in the address specified by
.Fa vpp .
.Pp
The argument
.Fa mp
is the mount point for the file system to create the file in.
.Pp
The argument
.Fa dvp
points to the directory to create the file in.
.Pp
The argument
.Fa vap
points to the attributes for the file to create.
.Pp
The argument
.Fa cred
holds the credentials for the file to create.
.Pp
The argument
.Fa extra
allows the caller to pass more information about the file to create.
.Pp
If a vnode is successfully created zero is returned, otherwise an
appropriate error code is returned.
.It Fn vcache_rekey_enter "mp" "vp" "old_key" "old_key_len" "new_key" "new_key_len"
Prepare to change the key of a cached vnode.
.Pp
The argument
.Fa mp
is the mount point for the file system the vnode
.Fa vp
resides in.
.Pp
The arguments
.Fa old_key
and
.Fa old_key_len
identify the cached vnode.
.Pp
The arguments
.Fa new_key
and
.Fa new_key_len
will identify the vnode after rename.
.Pp
If the new key already exists
.Er EEXIST
is returned, otherwise zero is returned.
.It Fn vcache_rekey_exit "mp" "vp" "old_key" "old_key_len" "new_key" "new_key_len"
Finish rename after calling
.Fn vcache_rekey_enter .
.It Fn vrecycle "vp"
Recycle the referenced vnode
.Fa vp
if this is the last reference.
.Fn vrecycle
is a null operation if the reference count is greater than one.
.It Fn vgone "vp"
Eliminate all activity associated with the unlocked vnode
.Fa vp
in preparation for recycling.
This operation is restricted to suspended file systems.
See
.Xr vfs_suspend 9 .
.It Fn vgonel "vp" "p"
Eliminate all activity associated with the locked vnode
.Fa vp
in preparation for recycling.
.It Fn vdead_check "vp" "flags"
Check the vnode
.Fa vp
for being or becoming dead.
Returns
.Er ENOENT
for a dead vnode and zero otherwise.
If
.Fa flags
is
.Dv VDEAD_NOWAIT
it will return
.Er EBUSY
if the vnode is becoming dead and the function will not sleep.
.Pp
Whenever this function returns a non-zero value all future calls
for this
.Fa vp
will also return a non-zero value.
.It Fn vflush "mp" "skipvp" "flags"
Remove any vnodes in the vnode table belonging to mount point
.Fa mp .
If
.Fa skipvp
is not
.Dv NULL
it is exempt from being flushed.
The argument
.Fa flags
is a set of flags modifying the operation of
.Fn vflush .
If
.Dv FORCECLOSE
is not specified, there should not be any active vnodes and
the error
.Er EBUSY
is returned if any are found (this is a user error, not a system error).
If
.Dv FORCECLOSE
is specified, active vnodes that are found are detached.
If
.Dv WRITECLOSE
is set, only flush out regular file vnodes open for writing.
SKIPSYSTEM causes any vnodes marked
.Dv V_SYSTEM
to be skipped.
.It Fn bdevvp "dev" "vpp"
Create a vnode for a block device.
.Fn bdevvp
is used for root file systems, swap areas and for memory file system
special devices.
.It Fn cdevvp "dev" "vpp"
Create a vnode for a character device.
.Fn cdevvp
is used for the console and kernfs special devices.
.It Fn vfinddev "dev" "vtype" "vpp"
Lookup a vnode by device number.
The vnode is referenced and returned in the address specified by
.Fa vpp .
.It Fn vdevgone "int maj" "int min" "int minh" "enum vtype type"
Reclaim all vnodes that correspond to the specified minor number range
.Fa minl
to
.Fa minh
(endpoints inclusive) of the specified major
.Fa maj .
.It Fn vwakeup "bp"
Update outstanding I/O count
.Em vp->v_numoutput
for the vnode
.Em bp->b_vp
and do a wakeup if requested and
.Em vp->vflag
has
.Dv VBWAIT
set.
.It Fn vflushbuf "vp" "sync"
Flush all dirty buffers to disk for the file with the locked vnode
.Fa vp .
The argument
.Fa sync
specifies whether the I/O should be synchronous and
.Fn vflushbuf
will sleep until
.Em vp->v_numoutput
is zero and
.Em vp->v_dirtyblkhd
is empty.
.It Fn vinvalbuf "vp" "flags" "cred" "l" "slpflag" "slptimeo"
Flush out and invalidate all buffers associated with locked vnode
.Fa vp .
The argument
.Fa l
and
.Fa cred
specified the calling process and its credentials.
The
.Xr ltsleep 9
flag and timeout are specified by the arguments
.Fa slpflag
and
.Fa slptimeo
respectively.
If the operation is successful zero is returned, otherwise an
appropriate error code is returned.
.It Fn vtruncbuf "vp" "lbn" "slpflag" "slptimeo"
Destroy any in-core buffers past the file truncation length for the
locked vnode
.Fa vp .
The truncation length is specified by
.Fa lbn .
.Fn vtruncbuf
will sleep while the I/O is performed,  The
.Xr ltsleep 9
flag and timeout are specified by the arguments
.Fa slpflag
and
.Fa slptimeo
respectively.
If the operation is successful zero is returned, otherwise an
appropriate error code is returned.
.It Fn vprint "label" "vp"
This function is used by the kernel to dump vnode information during a
panic.
It is only used if the kernel option DIAGNOSTIC is compiled into the kernel.
The argument
.Fa label
is a string to prefix the information dump of vnode
.Fa vp .
.El
.Sh CODE REFERENCES
The vnode framework is implemented within the file
.Pa sys/kern/vfs_subr.c .
.Sh SEE ALSO
.Xr intro 9 ,
.Xr lock 9 ,
.Xr namecache 9 ,
.Xr namei 9 ,
.Xr uvm 9 ,
.Xr vattr 9 ,
.Xr vfs 9 ,
.Xr vfsops 9 ,
.Xr vnodeops 9 ,
.Xr vnsubr 9
.Sh BUGS
The locking protocol is inconsistent.
Many vnode operations are passed locked vnodes on entry but release
the lock before they exit.
The locking protocol is used in some places to attempt to make a
series of operations atomic (e.g., access check then operation).
This does not work for non-local file systems that do not support locking
(e.g., NFS).
The
.Nm
interface would benefit from a simpler locking protocol.