diff options
Diffstat (limited to 'static/openbsd/man9/vnode.9')
| -rw-r--r-- | static/openbsd/man9/vnode.9 | 416 |
1 files changed, 416 insertions, 0 deletions
diff --git a/static/openbsd/man9/vnode.9 b/static/openbsd/man9/vnode.9 new file mode 100644 index 00000000..033e27b7 --- /dev/null +++ b/static/openbsd/man9/vnode.9 @@ -0,0 +1,416 @@ +.\" $OpenBSD: vnode.9,v 1.36 2025/10/18 10:57:42 mvs Exp $ +.\" +.\" Copyright (c) 2001 Constantine Sapuntzakis +.\" All rights reserved. +.\" +.\" 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. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED ``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 AUTHOR 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 $Mdocdate: October 18 2025 $ +.Dt VNODE 9 +.Os +.Sh NAME +.Nm vnode +.Nd an overview of vnodes +.Sh DESCRIPTION +A +.Em vnode +is an object in kernel memory that speaks the +.Ux +file interface (open, read, write, close, readdir, etc.). +Vnodes can represent files, directories, FIFOs, domain sockets, block devices, +character devices. +.Pp +Each vnode has a set of methods which start with the string +.Dq VOP_ . +These methods include +.Fn VOP_OPEN , +.Fn VOP_READ , +.Fn VOP_WRITE , +.Fn VOP_RENAME , +.Fn VOP_CLOSE , +and +.Fn VOP_MKDIR . +Many of these methods correspond closely to the equivalent +file system call \- +.Xr open 2 , +.Xr read 2 , +.Xr write 2 , +.Xr rename 2 , +etc. +Each file system (FFS, NFS, etc.) provides implementations for these methods. +.Pp +The Virtual File System library (see +.Xr vfs 9 ) +maintains a pool of vnodes. +File systems cannot allocate their own vnodes; they must use the functions +provided by the VFS to create and manage vnodes. +.Pp +The definition of a vnode is as follows: +.Bd -literal +struct vnode { + struct uvm_vnode *v_uvm; /* uvm data */ + const struct vops *v_op; /* vnode operations vector */ + enum vtype v_type; /* vnode type */ + enum vtagtype v_tag; /* type of underlying data */ + u_int v_flag; /* vnode flags (see below) */ + u_int v_usecount; /* reference count of users */ + u_int v_uvcount; /* unveil references */ + /* reference count of writers */ + u_int v_writecount; + /* Flags that can be read/written in interrupts */ + u_int v_bioflag; + u_int v_holdcnt; /* buffer references */ + u_int v_id; /* capability identifier */ + u_int v_inflight; + struct mount *v_mount; /* ptr to vfs we are in */ + TAILQ_ENTRY(vnode) v_freelist; /* vnode freelist */ + LIST_ENTRY(vnode) v_mntvnodes; /* vnodes for mount point */ + struct buf_rb_bufs v_bufs_tree; /* lookup of all bufs */ + struct buflists v_cleanblkhd; /* clean blocklist head */ + struct buflists v_dirtyblkhd; /* dirty blocklist head */ + u_int v_numoutput; /* num of writes in progress */ + LIST_ENTRY(vnode) v_synclist; /* vnode with dirty buffers */ + union { + struct mount *vu_mountedhere;/* ptr to mounted vfs (VDIR) */ + struct socket *vu_socket; /* unix ipc (VSOCK) */ + struct specinfo *vu_specinfo; /* device (VCHR, VBLK) */ + struct fifoinfo *vu_fifoinfo; /* fifo (VFIFO) */ + } v_un; + + /* VFS namecache */ + struct namecache_rb_cache v_nc_tree; + TAILQ_HEAD(, namecache) v_cache_dst; /* cache entries to us */ + + void *v_data; /* private data for fs */ + struct klist v_klist; /* identity of poller(s) */ +}; +#define v_mountedhere v_un.vu_mountedhere +#define v_socket v_un.vu_socket +#define v_specinfo v_un.vu_specinfo +#define v_fifoinfo v_un.vu_fifoinfo +.Ed +.Ss Vnode life cycle +When a client of the VFS requests a new vnode, the vnode allocation +code can reuse an old vnode object that is no longer in use. +Whether a vnode is in use is tracked by the vnode reference count +.Pq Va v_usecount . +By convention, each open file handle holds a reference +as do VM objects backed by files. +A vnode with a reference count of 1 or more will not be deallocated or +reused to point to a different file. +So, if you want to ensure that your vnode doesn't become a different +file under you, you better be sure you have a reference to it. +A vnode that points to a valid file and has a reference count of 1 or more +is called +.Em active . +.Pp +When a vnode's reference count drops to zero, it becomes +.Em inactive , +that is, a candidate for reuse. +An inactive vnode still refers to a valid file and one can try to +reactivate it using +.Xr vget 9 +(this is used a lot by caches). +.Pp +Before the VFS can reuse an inactive vnode to refer to another file, +it must clean all information pertaining to the old file. +A cleaned out vnode is called a +.Em reclaimed +vnode. +.Pp +To support forceable unmounts and the +.Xr revoke 2 +system call, the VFS may reclaim a vnode with a positive reference +count. +The reclaimed vnode is given to the dead file system, which +returns errors for most operations. +The reclaimed vnode will not be +reused for another file until its reference count hits zero. +.Ss Vnode pool +The +.Xr getnewvnode 9 +call allocates a vnode from the pool, possibly reusing an +inactive vnode, and returns it to the caller. +The vnode returned has a reference count +.Pq Va v_usecount +of 1. +.Pp +The +.Xr vref 9 +call increments the reference count on the vnode. +It may only be on a vnode with reference count of 1 or greater. +The +.Xr vrele 9 +and +.Xr vput 9 +calls decrement the reference count. +In addition, the +.Xr vput 9 +call also releases the vnode lock. +.Pp +The +.Xr vget 9 +call, when used on an inactive vnode, will make the vnode active +by bumping the reference count to one. +When called on an active vnode, +.Fn vget +increases the reference count by one. +However, if the vnode is being reclaimed concurrently, then +.Fn vget +will fail and return an error. +.Pp +The +.Xr vgone 9 +and +.Xr vgonel 9 +calls +orchestrate the reclamation of a vnode. +They can be called on both active and inactive vnodes. +.Pp +When transitioning a vnode to the reclaimed state, the VFS will call the +.Xr VOP_RECLAIM 9 +method. +File systems use this method to free any file-system-specific data +they attached to the vnode. +.Ss Vnode locks +The vnode actually has two different types of locks: the vnode lock +and the vnode reclamation lock +.Pq Dv VXLOCK . +.Ss The vnode lock +The vnode lock and its consistent use accomplishes the following: +.Bl -bullet +.It +It keeps a locked vnode from changing across certain pairs of VOP_ calls, +thus preserving cached data. +For example, it keeps the directory from +changing between a +.Xr VOP_LOOKUP 9 +call and a +.Xr VOP_CREATE 9 . +The +.Fn VOP_LOOKUP +call makes sure the name doesn't already exist in the +directory and finds free room in the directory for the new entry. +The +.Fn VOP_CREATE +call can then go ahead and create the file without checking if +it already exists or looking for free space. +.It +Some file systems rely on it to ensure that only one +.Dq thread +at a time +is calling VOP_ vnode operations on a given file or directory. +Otherwise, the file system's behavior is undefined. +.It +On rare occasions, code will hold the vnode lock so that a series of +VOP_ operations occurs as an atomic unit. +(Of course, this doesn't work with network file systems like NFSv2 that don't +have any notion of bundling a bunch of operations into an atomic unit.) +.It +While the vnode lock is held, the vnode will not be reclaimed. +.El +.Pp +There is a discipline to using the vnode lock. +Some VOP_ operations require that the vnode lock is held before being called. +.Pp +The vnode lock is acquired by calling +.Xr vn_lock 9 +and released by calling +.Xr VOP_UNLOCK 9 . +.Pp +A process is allowed to sleep while holding the vnode lock. +.Pp +The implementation of the vnode lock is the responsibility of the individual +file systems. +Not all file systems implement it. +.Pp +To prevent deadlocks, when acquiring locks on multiple vnodes, the lock +of parent directory must be acquired before the lock on the child directory. +.Ss Other vnode synchronization +The vnode reclamation lock +.Pq Dv VXLOCK +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. +The +.Dv VXWANT +flag is set by processes that wish to be woken up when reclamation +is finished. +.Pp +The +.Xr vwaitforio 9 +call is used to wait for all outstanding write I/Os associated with a +vnode to complete. +.Ss Version number/capability +The vnode capability, +.Va v_id , +is a 32-bit version number on the vnode. +Every time a vnode is reassigned to a new file, the vnode capability +is changed. +This is used by code that wishes to keep pointers to vnodes but doesn't want +to hold a reference (e.g., caches). +The code keeps both a vnode pointer and a copy of the capability. +The code can later compare the vnode's capability to its copy and see +if the vnode still points to the same file. +.Pp +Note: for this to work, memory assigned to hold a +.Vt struct vnode +can +only be used for another purpose when all pointers to it have disappeared. +Since the vnode pool has no way of knowing when all pointers have +disappeared, it never frees memory it has allocated for vnodes. +.Ss Vnode fields +Most of the fields of the vnode structure should be treated as opaque +and only manipulated through the proper APIs. +This section describes the fields that are manipulated directly. +.Pp +The +.Va v_flag +attribute contains random flags related to various functions. +They are summarized in the following table: +.Pp +.Bl -tag -width 10n -compact -offset indent +.It Dv VROOT +This vnode is the root of its file system. +.It Dv VTEXT +This vnode is a pure text prototype. +.It Dv VSYSTEM +This vnode is being used by kernel. +.It Dv VISTTY +This vnode represents a +.Xr tty 4 . +.It Dv VXLOCK +This vnode is locked to change its underlying type. +.It Dv VXWANT +A process is waiting for this vnode. +.It Dv VALIASED +This vnode has an alias. +.It Dv VLOCKSWORK +This vnode's underlying file system supports locking discipline. +.El +.Pp +The +.Va v_tag +attribute indicates what file system the vnode belongs to. +Very little code actually uses this attribute and its use is deprecated. +Programmers should seriously consider using more object-oriented approaches +(e.g. function tables). +There is no safe way of defining new +.Va v_tag Ns 's +for loadable file systems. +The +.Va v_tag +attribute is read-only. +.Pp +The +.Va v_type +attribute indicates what type of file (e.g. directory, +regular, FIFO) this vnode is. +This is used by the generic code for various checks. +For example, the +.Xr read 2 +system call returns zero when a read is attempted on a directory. +.Pp +Possible types are: +.Pp +.Bl -tag -width 10n -offset indent -compact +.It Dv VNON +This vnode has no type. +.It Dv VREG +This vnode represents a regular file. +.It Dv VDIR +This vnode represents a directory. +.It Dv VBLK +This vnode represents a block device. +.It Dv VCHR +This vnode represents a character device. +.It Dv VLNK +This vnode represents a symbolic link. +.It Dv VSOCK +This vnode represents a socket. +.It Dv VFIFO +This vnode represents a named pipe. +.It Dv VBAD +This vnode represents a bad or dead file. +.El +.Pp +The +.Va v_data +attribute allows a file system to attach a piece of file +system specific memory to the vnode. +This contains information about the file that is specific to +the file system (such as an inode pointer in the case of FFS). +.Pp +The +.Va v_numoutput +attribute indicates the number of pending synchronous +and asynchronous writes on the vnode. +It does not track the number of dirty buffers attached to the vnode. +The attribute is used by code like +.Xr fsync 2 +to wait for all writes +to complete before returning to the user. +This attribute must be manipulated at +.Xr splbio 9 . +.Pp +The +.Va v_writecount +attribute tracks the number of write calls pending +on the vnode. +.Ss Rules +The vast majority of vnode functions may not be called from interrupt +context. +The exceptions are +.Fn bgetvp +and +.Fn brelvp . +The following fields of the vnode are manipulated at interrupt level: +.Va v_numoutput , v_holdcnt , v_dirtyblkhd , +.Va v_cleanblkhd , v_bioflag , v_freelist , +and +.Va v_synclist . +Any access to these fields should be protected by +.Xr splbio 9 . +.Sh SEE ALSO +.Xr uvn_attach 9 , +.Xr vaccess 9 , +.Xr vclean 9 , +.Xr vcount 9 , +.Xr vdevgone 9 , +.Xr vfinddev 9 , +.Xr vflush 9 , +.Xr vflushbuf 9 , +.Xr vfs 9 , +.Xr vget 9 , +.Xr vgone 9 , +.Xr vhold 9 , +.Xr vinvalbuf 9 , +.Xr vn_lock 9 , +.Xr VOP_LOOKUP 9 , +.Xr vput 9 , +.Xr vrecycle 9 , +.Xr vref 9 , +.Xr vrele 9 , +.Xr vwaitforio 9 , +.Xr vwakeup 9 +.Sh HISTORY +This document first appeared in +.Ox 2.9 . |