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 February 12, 2014 30.Dt VNODE 9 31.Os 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 from the freelist is handled by 73.Xr getnewvnode 9 . 74The third is a count of the number of clients which are writing into 75the file. 76It 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. 89When the caller is finished with the vnode, it 90should release this reference by calling 91.Xr vrele 9 92(or 93.Xr vput 9 94if the vnode is locked). 95.Pp 96Other commonly used members of the vnode structure are 97.Va v_id 98which is used to maintain consistency in the name cache, 99.Va v_mount 100which points at the file system which owns the vnode, 101.Va v_type 102which contains the type of object the vnode represents and 103.Va v_data 104which is used by file systems to store file system specific data with 105the vnode. 106The 107.Va v_op 108field is used by the 109.Dv VOP_* 110macros to call functions in the file system which implement the vnode's 111functionality. 112.Sh VNODE TYPES 113.Bl -tag -width VSOCK 114.It Dv VNON 115No type. 116.It Dv VREG 117A regular file; may be with or without VM object backing. 118If you want to make sure this get a backing object, call 119.Fn vnode_create_vobject . 120.It Dv VDIR 121A directory. 122.It Dv VBLK 123A block device; may be with or without VM object backing. 124If you want to make sure this get a backing object, call 125.Fn vnode_create_vobject . 126.It Dv VCHR 127A character device. 128.It Dv VLNK 129A symbolic link. 130.It Dv VSOCK 131A socket. 132Advisory locking will not work on this. 133.It Dv VFIFO 134A FIFO (named pipe). 135Advisory locking will not work on this. 136.It Dv VBAD 137Indicates that the vnode has been reclaimed. 138.El 139.Sh IMPLEMENTATION NOTES 140VFIFO uses the "struct fileops" from 141.Pa /sys/kern/sys_pipe.c . 142VSOCK uses the "struct fileops" from 143.Pa /sys/kern/sys_socket.c . 144Everything else uses the one from 145.Pa /sys/kern/vfs_vnops.c . 146.Pp 147The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is 148an artifact of an incomplete integration of the VFS code into the 149kernel. 150.Pp 151Calls to 152.Xr malloc 9 153or 154.Xr free 9 155when holding a 156.Nm 157interlock, will cause a LOR (Lock Order Reversal) due to the 158intertwining of VM Objects and Vnodes. 159.Sh SEE ALSO 160.Xr malloc 9 , 161.Xr VOP_ACCESS 9 , 162.Xr VOP_ACLCHECK 9 , 163.Xr VOP_ADVISE 9 , 164.Xr VOP_ADVLOCK 9 , 165.Xr VOP_ALLOCATE 9 , 166.Xr VOP_ATTRIB 9 , 167.Xr VOP_BWRITE 9 , 168.Xr VOP_CREATE 9 , 169.Xr VOP_FSYNC 9 , 170.Xr VOP_GETACL 9 , 171.Xr VOP_GETEXTATTR 9 , 172.Xr VOP_GETPAGES 9 , 173.Xr VOP_INACTIVE 9 , 174.Xr VOP_IOCTL 9 , 175.Xr VOP_LINK 9 , 176.Xr VOP_LISTEXTATTR 9 , 177.Xr VOP_LOCK 9 , 178.Xr VOP_LOOKUP 9 , 179.Xr VOP_OPENCLOSE 9 , 180.Xr VOP_PATHCONF 9 , 181.Xr VOP_PRINT 9 , 182.Xr VOP_RDWR 9 , 183.Xr VOP_READDIR 9 , 184.Xr VOP_READLINK 9 , 185.Xr VOP_REALLOCBLKS 9 , 186.Xr VOP_REMOVE 9 , 187.Xr VOP_RENAME 9 , 188.Xr VOP_REVOKE 9 , 189.Xr VOP_SETACL 9 , 190.Xr VOP_SETEXTATTR 9 , 191.Xr VOP_STRATEGY 9 , 192.Xr VOP_VPTOCNP 9 , 193.Xr VOP_VPTOFH 9 , 194.Xr VFS 9 195.Sh AUTHORS 196This manual page was written by 197.An Doug Rabson . 198