1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 1996 Doug Rabson 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd June 30, 1999 32.Os 33.Dt VNODE 9 34.Sh NAME 35.Nm vnode 36.Nd internal representation of a file or directory 37.Sh SYNOPSIS 38.In sys/param.h 39.In sys/vnode.h 40.Pp 41.Bd -literal 42/* 43 * Vnode types. VNON means no type. 44 */ 45enum vtype { VNON, VREG, VDIR, VBLK, VCHR, VLNK, VSOCK, VFIFO, VBAD }; 46 47/* 48 * Vnode tag types. 49 * These are for the benefit of external programs only (e.g., pstat) 50 * and should NEVER be inspected by the kernel. 51 */ 52enum vtagtype { 53 VT_NON, VT_UFS, VT_NFS, VT_UNUSED, VT_PC, VT_LFS, VT_LOFS, VT_FDESC, 54 VT_PORTAL, VT_NULL, VT_UMAP, VT_KERNFS, VT_PROCFS, VT_AFS, VT_ISOFS, 55 VT_UNION, VT_MSDOSFS, VT_DEVFS, VT_TFS, VT_VFS, VT_CODA, VT_NTFS, 56 VT_HPFS, VT_NWFS, VT_PSEUDOFS 57}; 58 59/* 60 * Each underlying filesystem allocates its own private area and hangs 61 * it from v_data. If non-null, this area is freed in getnewvnode(). 62 */ 63TAILQ_HEAD(buflists, buf); 64 65typedef int vop_t __P((void *)); 66struct namecache; 67 68/* 69 * Reading or writing any of these items requires holding the appropriate lock. 70 * v_freelist is locked by the global vnode_free_list simple lock. 71 * v_mntvnodes is locked by the global mntvnodes simple lock. 72 * v_flag, v_usecount, v_holdcount and v_writecount are 73 * locked by the v_interlock simple lock. 74 * v_pollinfo is locked by the lock contained inside it. 75 */ 76struct vnode { 77 u_long v_flag; /* vnode flags (see below) */ 78 int v_usecount; /* reference count of users */ 79 int v_writecount; /* reference count of writers */ 80 int v_holdcnt; /* page & buffer references */ 81 u_long v_id; /* capability identifier */ 82 struct mount *v_mount; /* ptr to vfs we are in */ 83 vop_t **v_op; /* vnode operations vector */ 84 TAILQ_ENTRY(vnode) v_freelist; /* vnode freelist */ 85 LIST_ENTRY(vnode) v_mntvnodes; /* vnodes for mount point */ 86 struct buflists v_cleanblkhd; /* clean blocklist head */ 87 struct buflists v_dirtyblkhd; /* dirty blocklist head */ 88 LIST_ENTRY(vnode) v_synclist; /* vnodes with dirty buffers */ 89 long v_numoutput; /* num of writes in progress */ 90 enum vtype v_type; /* vnode type */ 91 union { 92 struct mount *vu_mountedhere;/* ptr to mounted vfs (VDIR) */ 93 struct socket *vu_socket; /* unix ipc (VSOCK) */ 94 struct { 95 struct specinfo *vu_specinfo; /* device (VCHR, VBLK) */ 96 SLIST_ENTRY(vnode) vu_specnext; 97 } vu_spec; 98 struct fifoinfo *vu_fifoinfo; /* fifo (VFIFO) */ 99 } v_un; 100 struct nqlease *v_lease; /* Soft reference to lease */ 101 daddr_t v_lastw; /* last write (write cluster) */ 102 daddr_t v_cstart; /* start block of cluster */ 103 daddr_t v_lasta; /* last allocation */ 104 int v_clen; /* length of current cluster */ 105 struct vm_object *v_object; /* Place to store VM object */ 106 struct simplelock v_interlock; /* lock on usecount and flag */ 107 struct lock *v_vnlock; /* used for non-locking fs's */ 108 enum vtagtype v_tag; /* type of underlying data */ 109 void *v_data; /* private data for fs */ 110 LIST_HEAD(, namecache) v_cache_src; /* Cache entries from us */ 111 TAILQ_HEAD(, namecache) v_cache_dst; /* Cache entries to us */ 112 struct vnode *v_dd; /* .. vnode */ 113 u_long v_ddid; /* .. capability identifier */ 114 struct { 115 struct simplelock vpi_lock; /* lock to protect below */ 116 struct selinfo vpi_selinfo; /* identity of poller(s) */ 117 short vpi_events; /* what they are looking for */ 118 short vpi_revents; /* what has happened */ 119 } v_pollinfo; 120}; 121#define v_mountedhere v_un.vu_mountedhere 122#define v_socket v_un.vu_socket 123#define v_rdev v_un.vu_spec.vu_specinfo 124#define v_specnext v_un.vu_spec.vu_specnext 125#define v_fifoinfo v_un.vu_fifoinfo 126 127/* 128 * Vnode flags. 129 */ 130#define VROOT 0x00001 /* root of its filesystem */ 131#define VTEXT 0x00002 /* vnode is a pure text prototype */ 132#define VSYSTEM 0x00004 /* vnode being used by kernel */ 133#define VISTTY 0x00008 /* vnode represents a tty */ 134#define VXLOCK 0x00100 /* vnode is locked to change underlying type */ 135#define VXWANT 0x00200 /* process is waiting for vnode */ 136#define VBWAIT 0x00400 /* waiting for output to complete */ 137#define VOBJBUF 0x02000 /* Allocate buffers in VM object */ 138#define VAGE 0x08000 /* Insert vnode at head of free list */ 139#define VOLOCK 0x10000 /* vnode is locked waiting for an object */ 140#define VOWANT 0x20000 /* a process is waiting for VOLOCK */ 141#define VDOOMED 0x40000 /* This vnode is being recycled */ 142#define VFREE 0x80000 /* This vnode is on the freelist */ 143#define VTBFREE 0x100000 /* This vnode is on the to-be-freelist */ 144#define VONWORKLST 0x200000 /* On syncer work-list */ 145#define VMOUNT 0x400000 /* Mount in progress */ 146 147.Ed 148.Sh DESCRIPTION 149The vnode is the focus of all file activity in 150.Ux . 151There is a 152unique vnode allocated for each active file, each current directory, 153each mounted-on file, text file, and the root. 154.Pp 155Each vnode has three reference counts, 156.Dv v_usecount , 157.Dv v_holdcnt 158and 159.Dv v_writecount . 160The first is the number of clients within the kernel which are 161using this vnode. This count is maintained by 162.Xr vref 9 , 163.Xr vrele 9 164and 165.Xr vput 9 . 166The second is the number of clients within the kernel who veto 167the recycling of this vnode. This count is 168maintained by 169.Xr vhold 9 170and 171.Xr vdrop 9 . 172When both the 173.Dv v_usecount 174and the 175.Dv v_holdcnt 176of a vnode reaches zero then the vnode will be put on the freelist 177and may be reused for another file, possibly in another filesystem. 178The transition to and from the freelist is handled by 179.Xr getnewvnode 9 , 180.Xr vfree 9 181and 182.Xr vbusy 9 . 183The third is a count of the number of clients which are writing into 184the file. It is maintained by the 185.Xr open 2 186and 187.Xr close 2 188system calls. 189.Pp 190Any call which returns a vnode (e.g.\& 191.Xr VFS_GET 9 , 192.Xr VOP_LOOKUP 9 193etc.) 194will increase the 195.Dv v_usecount 196of the vnode by one. When the caller is finished with the vnode, it 197should release this reference by calling 198.Xr vrele 9 199(or 200.Xr vput 9 201if the vnode is locked). 202.Pp 203Other commonly used members of the vnode structure are 204.Dv v_id 205which is used to maintain consistency in the name cache, 206.Dv v_mount 207which points at the filesystem which owns the vnode, 208.Dv v_type 209which contains the type of object the vnode represents and 210.Dv v_data 211which is used by filesystems to store filesystem specific data with 212the vnode. 213The 214.Dv v_op 215field is used by the 216.Dv VOP_* 217macros to call functions in the filesystem which implement the vnode's 218functionality. 219.Sh VNODE TYPES 220.Bl -tag -width VSOCK 221.It Dv VNON 222No type. 223.It Dv VREG 224A regular file; may be with or without VM object backing. If you want 225to make sure this get a backing object, call 226.Xr vfs_object_create 9 . 227.It Dv VDIR 228A directory. 229.It Dv VBLK 230A block device; may be with or without VM object backing. If you want 231to make sure this get a backing object, call 232.Xr vfs_object_create 9 . 233.It Dv VCHR 234A character device. 235.It Dv VLNK 236A symbolic link. 237.It Dv VSOCK 238A socket. Advisory locking won't work on this. 239.It Dv VFIFO 240A FIFO (named pipe). Advisory locking won't work on this. 241.It Dv VBAD 242An old style bad sector map 243.El 244.Sh NOTES 245VFIFO uses the "struct fileops" from 246.Pa /sys/kern/sys_pipe.c . 247VSOCK uses the "struct fileops" from 248.Pa /sys/kern/sys_socket.c . 249Everything else uses the one from 250.Pa /sys/kern/vfs_vnops.c . 251.Pp 252The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is 253an artifact of an incomplete integration of the VFS code into the 254kernel. 255.Sh SEE ALSO 256.Xr VFS 9 257.Sh AUTHORS 258This man page was written by 259.An Doug Rabson . 260