1.\" Copyright (c) 1996 Doug Rabson 2.\" 3.\" All rights reserved. 4.\" 5.\" This program is free software. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd May 20, 2003 30.Os 31.Dt VNODE 9 32.Sh NAME 33.Nm vnode 34.Nd internal representation of a file or directory 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/vnode.h 38.Sh DESCRIPTION 39The vnode is the focus of all file activity in 40.Ux . 41A vnode is described by 42.Vt "struct vnode" . 43There is a 44unique vnode allocated for each active file, each current directory, 45each mounted-on file, text file, and the root. 46.Pp 47Each vnode has three reference counts, 48.Va v_usecount , 49.Va v_holdcnt 50and 51.Va v_writecount . 52The first is the number of clients within the kernel which are 53using this vnode. 54This count is maintained by 55.Xr vref 9 , 56.Xr vrele 9 57and 58.Xr vput 9 . 59The second is the number of clients within the kernel who veto 60the recycling of this vnode. 61This count is 62maintained by 63.Xr vhold 9 64and 65.Xr vdrop 9 . 66When both the 67.Va v_usecount 68and the 69.Va v_holdcnt 70of a vnode reaches zero then the vnode will be put on the freelist 71and may be reused for another file, possibly in another file system. 72The transition to and from the freelist is handled by 73.Xr getnewvnode 9 , 74.Xr vfree 9 75and 76.Xr vbusy 9 . 77The third is a count of the number of clients which are writing into 78the file. 79It is maintained by the 80.Xr open 2 81and 82.Xr close 2 83system calls. 84.Pp 85Any call which returns a vnode (e.g.\& 86.Xr vget 9 , 87.Xr VOP_LOOKUP 9 88etc.) 89will increase the 90.Va v_usecount 91of the vnode by one. 92When the caller is finished with the vnode, it 93should release this reference by calling 94.Xr vrele 9 95(or 96.Xr vput 9 97if the vnode is locked). 98.Pp 99Other commonly used members of the vnode structure are 100.Va v_id 101which is used to maintain consistency in the name cache, 102.Va v_mount 103which points at the file system which owns the vnode, 104.Va v_type 105which contains the type of object the vnode represents and 106.Va v_data 107which is used by file systems to store file system specific data with 108the vnode. 109The 110.Va v_op 111field is used by the 112.Dv VOP_* 113macros to call functions in the file system which implement the vnode's 114functionality. 115.Sh VNODE TYPES 116.Bl -tag -width VSOCK 117.It Dv VNON 118No type. 119.It Dv VREG 120A regular file; may be with or without VM object backing. 121If you want to make sure this get a backing object, call 122.Xr vfs_object_create 9 . 123.It Dv VDIR 124A directory. 125.It Dv VBLK 126A block device; may be with or without VM object backing. 127If you want to make sure this get a backing object, call 128.Xr vfs_object_create 9 . 129.It Dv VCHR 130A character device. 131.It Dv VLNK 132A symbolic link. 133.It Dv VSOCK 134A socket. 135Advisory locking will not work on this. 136.It Dv VFIFO 137A FIFO (named pipe). 138Advisory locking will not work on this. 139.It Dv VBAD 140An old style bad sector map 141.El 142.Sh IMPLEMENTATION NOTES 143VFIFO uses the "struct fileops" from 144.Pa /sys/kern/sys_pipe.c . 145VSOCK uses the "struct fileops" from 146.Pa /sys/kern/sys_socket.c . 147Everything else uses the one from 148.Pa /sys/kern/vfs_vnops.c . 149.Pp 150The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is 151an artifact of an incomplete integration of the VFS code into the 152kernel. 153.Pp 154Calls to 155.Xr malloc 9 156or 157.Xr free 9 158when holding a 159.Nm 160interlock, will cause a LOR (Lock Order Reversal) due to the 161intertwining of VM Objects and Vnodes. 162.Sh SEE ALSO 163.Xr malloc 9 , 164.Xr VFS 9 165.Sh AUTHORS 166This manual page was written by 167.An Doug Rabson . 168