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.Dd February 12, 2014 28.Dt VNODE 9 29.Os 30.Sh NAME 31.Nm vnode 32.Nd internal representation of a file or directory 33.Sh SYNOPSIS 34.In sys/param.h 35.In sys/vnode.h 36.Sh DESCRIPTION 37The vnode is the focus of all file activity in 38.Ux . 39A vnode is described by 40.Vt "struct vnode" . 41There is a 42unique vnode allocated for each active file, each current directory, 43each mounted-on file, text file, and the root. 44.Pp 45Each vnode has three reference counts, 46.Va v_usecount , 47.Va v_holdcnt 48and 49.Va v_writecount . 50The first is the number of clients within the kernel which are 51using this vnode. 52This count is maintained by 53.Xr vref 9 , 54.Xr vrele 9 55and 56.Xr vput 9 . 57The second is the number of clients within the kernel who veto 58the recycling of this vnode. 59This 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 from the freelist is handled by 71.Xr getnewvnode 9 . 72The third is a count of the number of clients which are writing into 73the file. 74It is maintained by the 75.Xr open 2 76and 77.Xr close 2 78system calls. 79.Pp 80Any call which returns a vnode (e.g.,\& 81.Xr vget 9 , 82.Xr VOP_LOOKUP 9 , 83etc.\&) 84will increase the 85.Va v_usecount 86of the vnode by one. 87When the caller is finished with the vnode, it 88should release this reference by calling 89.Xr vrele 9 90(or 91.Xr vput 9 92if the vnode is locked). 93.Pp 94Other commonly used members of the vnode structure are 95.Va v_id 96which is used to maintain consistency in the name cache, 97.Va v_mount 98which points at the file system which owns the vnode, 99.Va v_type 100which contains the type of object the vnode represents and 101.Va v_data 102which is used by file systems to store file system specific data with 103the vnode. 104The 105.Va v_op 106field is used by the 107.Dv VOP_* 108macros to call functions in the file system which implement the vnode's 109functionality. 110.Sh VNODE TYPES 111.Bl -tag -width VSOCK 112.It Dv VNON 113No type. 114.It Dv VREG 115A regular file; may be with or without VM object backing. 116If you want to make sure this get a backing object, call 117.Fn vnode_create_vobject . 118.It Dv VDIR 119A directory. 120.It Dv VBLK 121A block device; may be with or without VM object backing. 122If you want to make sure this get a backing object, call 123.Fn vnode_create_vobject . 124.It Dv VCHR 125A character device. 126.It Dv VLNK 127A symbolic link. 128.It Dv VSOCK 129A socket. 130Advisory locking will not work on this. 131.It Dv VFIFO 132A FIFO (named pipe). 133Advisory locking will not work on this. 134.It Dv VBAD 135Indicates that the vnode has been reclaimed. 136.El 137.Sh IMPLEMENTATION NOTES 138VFIFO uses the "struct fileops" from 139.Pa /sys/kern/sys_pipe.c . 140VSOCK uses the "struct fileops" from 141.Pa /sys/kern/sys_socket.c . 142Everything else uses the one from 143.Pa /sys/kern/vfs_vnops.c . 144.Pp 145The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is 146an artifact of an incomplete integration of the VFS code into the 147kernel. 148.Pp 149Calls to 150.Xr malloc 9 151or 152.Xr free 9 153when holding a 154.Nm 155interlock, will cause a LOR (Lock Order Reversal) due to the 156intertwining of VM Objects and Vnodes. 157.Sh SEE ALSO 158.Xr malloc 9 , 159.Xr VFS 9 , 160.Xr VOP_ACCESS 9 , 161.Xr VOP_ACLCHECK 9 , 162.Xr VOP_ADVISE 9 , 163.Xr VOP_ADVLOCK 9 , 164.Xr VOP_ALLOCATE 9 , 165.Xr VOP_ATTRIB 9 , 166.Xr VOP_BWRITE 9 , 167.Xr VOP_CREATE 9 , 168.Xr VOP_FSYNC 9 , 169.Xr VOP_GETACL 9 , 170.Xr VOP_GETEXTATTR 9 , 171.Xr VOP_GETPAGES 9 , 172.Xr VOP_INACTIVE 9 , 173.Xr VOP_IOCTL 9 , 174.Xr VOP_LINK 9 , 175.Xr VOP_LISTEXTATTR 9 , 176.Xr VOP_LOCK 9 , 177.Xr VOP_LOOKUP 9 , 178.Xr VOP_OPENCLOSE 9 , 179.Xr VOP_PATHCONF 9 , 180.Xr VOP_PRINT 9 , 181.Xr VOP_RDWR 9 , 182.Xr VOP_READ_PGCACHE 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_SETLABEL 9 , 192.Xr VOP_STRATEGY 9 , 193.Xr VOP_VPTOCNP 9 , 194.Xr VOP_VPTOFH 9 195.Sh AUTHORS 196This manual page was written by 197.An Doug Rabson . 198