diff options
Diffstat (limited to 'share')
| -rw-r--r-- | share/man/man9/vnode.9 | 76 |
1 files changed, 28 insertions, 48 deletions
diff --git a/share/man/man9/vnode.9 b/share/man/man9/vnode.9 index e204d5a5e4c..6323a738d83 100644 --- a/share/man/man9/vnode.9 +++ b/share/man/man9/vnode.9 @@ -5,35 +5,32 @@ .Nm vnode .Nd an overview of vnodes .Sh DESCRIPTION - The vnode is the kernel object that corresponds to a file (actually, a file, a directory, a fifo, a domain socket, a symlink, or a device). - +.Pp Each vnode has a set of methods corresponding to file operations (vop_open, vop_read, vop_write, vop_rename, vop_mkdir, vop_close). These methods are implemented by the individual file systems and are dispatched through function pointers. - +.Pp In addition, the VFS has functions for maintaining a pool of vnodes, associating vnodes with mount points, and associating vnodes with buffers. The individual file systems cannot override these functions. As such, individual file systems cannot allocate their own vnodes. - +.Pp In general, the contents of a struct vnode should not be examined or modified by the users of vnode methods. There are some rather common exceptions detailed later in this document. - +.Pp The vast majority of the vnode functions CANNOT be called from interrupt context. - .Ss Vnode pool - All the vnodes in the kernel are allocated out of a shared pool. The .Xr getnewvnode 9 system call returns a fresh vnode from the vnode pool. The vnode returned has a reference count (v_usecount) of 1. - +.Pp The .Xr vref 9 call increments the reference count on the vnode. The @@ -44,13 +41,13 @@ calls decrement the reference count. In addition, the .Xr vput 9 call also releases the vnode lock. - +.Pp When a vnode's reference count becomes zero, the vnode pool places it a pool of free vnodes, eligible to be assigned to a different file. The vnode pool calls the .Xr vop_inactive 9 method to inform the file system that the reference count has reached zero. - +.Pp When placed in the pool of free vnodes, the vnode is not otherwise altered. In fact, it can often be retrieved before it is reassigned to a different file. This is useful when the system closes a file and opens it again in rapid @@ -58,21 +55,21 @@ succession. The .Xr vget 9 call is used to revive the vnode. Note, callers should ensure the vnode they get back has not been reassigned to a different file. - +.Pp When the vnode pool decides to reclaim the vnode to satisfy a getnewvnode request, it calls the .Xr vop_reclaim 9 method. File systems often use this method to free any file-system specific data they attach to the vnode. - +.Pp A file system can force a vnode with a reference count of zero to be reclaimed earlier by calling the .Xr vrecycle 9 call. The .Xr vrecycle 9 call is a null operation if the reference count is greater than zero. - +.Pp The .Xr vgone 9 and @@ -82,9 +79,7 @@ the vnode even if it has a non-zero reference count. If the vnode had a non-zero reference count, the vnode is then assigned an operations vector corresponding to the "dead" file system. In this operations vector, most operations return errors. - .Ss Vnode locks - Note to beginners: locks don't actually prevent memory from being read or overwritten. Instead, they are an object that, where used, allows only one piece of code to proceed through the locked section. If you @@ -92,12 +87,10 @@ do not surround a stretch of code with a lock, it can and probably will eventually be executed simultaneously with other stretches of code (including stretches ). Chances are the results will be unexpected and disappointing to both the user and you. - +.Pp The vnode actually has three different types of lock: the vnode lock, the vnode interlock, and the vnode reclamation lock (VXLOCK). - .Ss The vnode lock - The most general lock is the vnode lock. This lock is acquired by calling .Xr vn_lock 9 @@ -107,7 +100,7 @@ and released by calling a given file when there are multiple concurrent requests on the same file. Many file system functions require that you hold the vnode lock on entry. The vnode lock may be held when sleeping. - +.Pp The .Xr revoke 2 and forceable unmount features in BSD UNIX allows a @@ -115,48 +108,42 @@ user to invalidate files and their associated vnodes at almost any time, even if there are active open files on it. While in a region of code protected by the vnode lock, the process is guaranteed that the vnode will not be reclaimed or invalidated. - +.Pp The vnode lock is a multiple-reader or single-writer lock. An exclusive vnode lock may be acquired multiple times by the same process. - +.Pp The vnode lock is somewhat messy because it is used for many purposes. Some clients of the vnode interface use it to try to bundle a series of VOP_ method calls into an atomic group. Many file systems rely on it to prevent race conditions in updating file system specific data structures (as opposed to having their own locks). - +.Pp The implementation of the vnode lock is the responsibility of the individual file systems. Not all file system 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. - +.Pp Interrupt handlers must not acquire vnode locks. - .Ss Vnode interlock - The vnode interlock (vp->v_interlock) is a spinlock. It is useful on multi-processor systems for acquiring a quick exclusive lock on the contents of the vnode. It MUST NOT be held while sleeping. (What fields does it cover? What about splbio/interrupt issues?) - +.Pp Operations on this lock are a no-op on uniprocessor systems. - .Ss Other Vnode synchronization - The vnode reclamation lock (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 VXWANT flag is set by processes that wish to woken up when reclamation is finished. - +.Pp The .Xr vwaitforio 9 call is used for to wait for all outstanding write I/Os associated with a vnode to complete. - .Ss Version number/capability - The vnode capability, 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 wish to keep pointers to vnodes @@ -164,49 +151,44 @@ but doesn't want to hold a reference (e.g. caches). The code keeps both a vnode * 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 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 v_flag attribute contains random flags related to various functions. They are summarized in table ... - +.Pp The 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 v_tags for loadable file systems. The v_tag attribute is read-only. - +.Pp The v_type attribute indicates what type of file (e.g. directory, regular, fifo) this vnode is. This is used by the generic code to ensure for various checks. For example, the .Xr read 2 system call returns an error when a read is attempted on a directory. - +.Pp The v_data attribute allows a file system to attach piece of file system specific memory to the vnode. This contains information about the file that is specific to the file system. - +.Pp The 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 fsync to wait for all writes to complete before returning to the user. This attribute must be manipulated at splbio(). - +.Pp The 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 bgetvp and brelvp. The following fields of the vnode are manipulated at interrupt level: v_numoutput, @@ -214,20 +196,18 @@ v_holdcnt, v_dirtyblkhd, v_cleanblkhd, v_bioflag, v_freelist, and v_synclist. Any accesses to these field should be protected by splbio, unless you are certain that there is no chance an interrupt handler will modify them. - +.Pp A vnode will only be reassigned to another file when its reference count reaches zero and the vnode lock is freed. - +.Pp A vnode will not be reclaimed as long as the vnode lock is held. If the vnode reference count drops to zero while a process is holding the vnode lock, the vnode MAY be queued for reclamation. Increasing the reference count from 0 to 1 while holding the lock will most likely cause intermittent kernel panics. - .Sh SEE ALSO .Sh HISTORY - This document first appeared in .Ox 2.9 . |