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. This count is maintained by 54.Xr vref 9 , 55.Xr vrele 9 56and 57.Xr vput 9 . 58The second is the number of clients within the kernel who veto 59the recycling of this vnode. This count is 60maintained by 61.Xr vhold 9 62and 63.Xr vdrop 9 . 64When both the 65.Va v_usecount 66and the 67.Va v_holdcnt 68of a vnode reaches zero then the vnode will be put on the freelist 69and may be reused for another file, possibly in another file system. 70The transition to and from the freelist is handled by 71.Xr getnewvnode 9 , 72.Xr vfree 9 73and 74.Xr vbusy 9 . 75The third is a count of the number of clients which are writing into 76the file. It is maintained by the 77.Xr open 2 78and 79.Xr close 2 80system calls. 81.Pp 82Any call which returns a vnode (e.g.\& 83.Xr vget 9 , 84.Xr VOP_LOOKUP 9 85etc.) 86will increase the 87.Va v_usecount 88of the vnode by one. When the caller is finished with the vnode, it 89should release this reference by calling 90.Xr vrele 9 91(or 92.Xr vput 9 93if the vnode is locked). 94.Pp 95Other commonly used members of the vnode structure are 96.Va v_id 97which is used to maintain consistency in the name cache, 98.Va v_mount 99which points at the file system which owns the vnode, 100.Va v_type 101which contains the type of object the vnode represents and 102.Va v_data 103which is used by file systems to store file system specific data with 104the vnode. 105The 106.Va v_op 107field is used by the 108.Dv VOP_* 109macros to call functions in the file system which implement the vnode's 110functionality. 111.Sh VNODE TYPES 112.Bl -tag -width VSOCK 113.It Dv VNON 114No type. 115.It Dv VREG 116A regular file; may be with or without VM object backing. If you want 117to make sure this get a backing object, call 118.Xr vfs_object_create 9 . 119.It Dv VDIR 120A directory. 121.It Dv VBLK 122A block device; may be with or without VM object backing. If you want 123to make sure this get a backing object, call 124.Xr vfs_object_create 9 . 125.It Dv VCHR 126A character device. 127.It Dv VLNK 128A symbolic link. 129.It Dv VSOCK 130A socket. Advisory locking won't work on this. 131.It Dv VFIFO 132A FIFO (named pipe). Advisory locking won't work on this. 133.It Dv VBAD 134An old style bad sector map 135.El 136.Sh IMPLEMENTATION NOTES 137VFIFO uses the "struct fileops" from 138.Pa /sys/kern/sys_pipe.c . 139VSOCK uses the "struct fileops" from 140.Pa /sys/kern/sys_socket.c . 141Everything else uses the one from 142.Pa /sys/kern/vfs_vnops.c . 143.Pp 144The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is 145an artifact of an incomplete integration of the VFS code into the 146kernel. 147.Pp 148Calls to 149.Xr malloc 9 150or 151.Xr free 9 152when holding a 153.Nm 154interlock, will cause a LOR (Lock Order Reversal) due to the 155intertwining of VM Objects and Vnodes. 156.Sh SEE ALSO 157.Xr malloc 9 , 158.Xr VFS 9 159.Sh AUTHORS 160This man page was written by 161.An Doug Rabson . 162