/share/man/man9/vnode.9

  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 13, 2010
 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 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.Fn vnode_create_vobject .
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.Fn vnode_create_vobject .
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
140Indicates that the vnode has been reclaimed.
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 VOP_ACCESS 9 ,
165.Xr VOP_ACLCHECK 9 ,
166.Xr VOP_ADVLOCK 9 ,
167.Xr VOP_ATTRIB 9 ,
168.Xr VOP_BWRITE 9 ,
169.Xr VOP_CREATE 9 ,
170.Xr VOP_FSYNC 9 ,
171.Xr VOP_GETACL 9 ,
172.Xr VOP_GETEXTATTR 9 ,
173.Xr VOP_GETPAGES 9 ,
174.Xr VOP_GETVOBJECT 9 ,
175.Xr VOP_INACTIVE 9 ,
176.Xr VOP_IOCTL 9 ,
177.Xr VOP_LINK 9 ,
178.Xr VOP_LISTEXTATTR 9 ,
179.Xr VOP_LOCK 9 ,
180.Xr VOP_LOOKUP 9 ,
181.Xr VOP_OPENCLOSE 9 ,
182.Xr VOP_PATHCONF 9 ,
183.Xr VOP_PRINT 9 ,
184.Xr VOP_RDWR 9 ,
185.Xr VOP_READDIR 9 ,
186.Xr VOP_READLINK 9 ,
187.Xr VOP_REALLOCBLKS 9 ,
188.Xr VOP_REMOVE 9 ,
189.Xr VOP_RENAME 9 ,
190.Xr VOP_REVOKE 9 ,
191.Xr VOP_SETACL 9 ,
192.Xr VOP_SETEXTATTR 9 ,
193.Xr VOP_STRATEGY 9 ,
194.Xr VOP_VPTOCNP 9 ,
195.Xr VOP_VPTOFH 9 ,
196.Xr VFS 9
197.Sh AUTHORS
198This manual page was written by
199.An Doug Rabson .