1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
<table class="head">
<tr>
<td class="head-ltitle">VNODE(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">VNODE(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">vnode</code> — <span class="Nd">internal
representation of a file or directory</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/param.h</a>></code>
<br/>
<code class="In">#include <<a class="In">sys/vnode.h</a>></code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The vnode is the focus of all file activity in
<span class="Ux">UNIX</span>. A vnode is described by <var class="Vt">struct
vnode</var>. There is a unique vnode allocated for each active file, each
current directory, each mounted-on file, text file, and the root.</p>
<p class="Pp">Each vnode has three reference counts,
<var class="Va">v_usecount</var>, <var class="Va">v_holdcnt</var> and
<var class="Va">v_writecount</var>. The first is the number of clients
within the kernel which are using this vnode. This count is maintained by
<a class="Xr">vref(9)</a>, <a class="Xr">vrele(9)</a> and
<a class="Xr">vput(9)</a>. The second is the number of clients within the
kernel who veto the recycling of this vnode. This count is maintained by
<a class="Xr">vhold(9)</a> and <a class="Xr">vdrop(9)</a>. When both the
<var class="Va">v_usecount</var> and the <var class="Va">v_holdcnt</var> of
a vnode reaches zero then the vnode will be put on the freelist and may be
reused for another file, possibly in another file system. The transition
from the freelist is handled by <a class="Xr">getnewvnode(9)</a>. The third
is a count of the number of clients which are writing into the file. It is
maintained by the <a class="Xr">open(2)</a> and <a class="Xr">close(2)</a>
system calls.</p>
<p class="Pp">Any call which returns a vnode (e.g., <a class="Xr">vget(9)</a>,
<a class="Xr">VOP_LOOKUP(9)</a>, etc.) will increase the
<var class="Va">v_usecount</var> of the vnode by one. When the caller is
finished with the vnode, it should release this reference by calling
<a class="Xr">vrele(9)</a> (or <a class="Xr">vput(9)</a> if the vnode is
locked).</p>
<p class="Pp" id="VOP_*">Other commonly used members of the vnode structure are
<var class="Va">v_id</var> which is used to maintain consistency in the name
cache, <var class="Va">v_mount</var> which points at the file system which
owns the vnode, <var class="Va">v_type</var> which contains the type of
object the vnode represents and <var class="Va">v_data</var> which is used
by file systems to store file system specific data with the vnode. The
<var class="Va">v_op</var> field is used by the
<a class="permalink" href="#VOP_*"><code class="Fn">VOP_*</code></a>()
functions to call functions in the file system which implement the vnode's
functionality.</p>
<p class="Pp" id="VOP_*~2">The
<a class="permalink" href="#VOP_*~2"><code class="Fn">VOP_*</code></a>()
function declarations and definitions are generated from
<span class="Pa">sys/kern/vnode_if.src</span> by the
<span class="Pa">sys/tools/vnode_if.awk</span> script. The interfaces are
documented in their respective manual pages like
<a class="Xr">VOP_READ(9)</a> and <a class="Xr">VOP_WRITE(9)</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="VNODE_TYPES"><a class="permalink" href="#VNODE_TYPES">VNODE
TYPES</a></h1>
<dl class="Bl-tag">
<dt id="VNON"><a class="permalink" href="#VNON"><code class="Dv">VNON</code></a></dt>
<dd>No type.</dd>
<dt id="VREG"><a class="permalink" href="#VREG"><code class="Dv">VREG</code></a></dt>
<dd>A regular file; may be with or without VM object backing. If you want to
make sure this get a backing object, call
<a class="permalink" href="#vnode_create_vobject"><code class="Fn" id="vnode_create_vobject">vnode_create_vobject</code></a>().</dd>
<dt id="VDIR"><a class="permalink" href="#VDIR"><code class="Dv">VDIR</code></a></dt>
<dd>A directory.</dd>
<dt id="VBLK"><a class="permalink" href="#VBLK"><code class="Dv">VBLK</code></a></dt>
<dd>A block device; may be with or without VM object backing. If you want to
make sure this get a backing object, call
<code class="Fn">vnode_create_vobject</code>().</dd>
<dt id="VCHR"><a class="permalink" href="#VCHR"><code class="Dv">VCHR</code></a></dt>
<dd>A character device.</dd>
<dt id="VLNK"><a class="permalink" href="#VLNK"><code class="Dv">VLNK</code></a></dt>
<dd>A symbolic link.</dd>
<dt id="VSOCK"><a class="permalink" href="#VSOCK"><code class="Dv">VSOCK</code></a></dt>
<dd>A socket. Advisory locking will not work on this.</dd>
<dt id="VFIFO"><a class="permalink" href="#VFIFO"><code class="Dv">VFIFO</code></a></dt>
<dd>A FIFO (named pipe). Advisory locking will not work on this.</dd>
<dt id="VBAD"><a class="permalink" href="#VBAD"><code class="Dv">VBAD</code></a></dt>
<dd>Indicates that the vnode has been reclaimed.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION
NOTES</a></h1>
<p class="Pp">VFIFO uses the "struct fileops" from
<span class="Pa">/sys/kern/sys_pipe.c</span>. VSOCK uses the "struct
fileops" from <span class="Pa">/sys/kern/sys_socket.c</span>.
Everything else uses the one from
<span class="Pa">/sys/kern/vfs_vnops.c</span>.</p>
<p class="Pp">The VFIFO/VSOCK code, which is why "struct fileops" is
used at all, is an artifact of an incomplete integration of the VFS code
into the kernel.</p>
<p class="Pp">Calls to <a class="Xr">malloc(9)</a> or <a class="Xr">free(9)</a>
when holding a <code class="Nm">vnode</code> interlock, will cause a LOR
(Lock Order Reversal) due to the intertwining of VM Objects and Vnodes.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag Bl-compact">
<dt><span class="Pa">sys/kern/vnode_if.src</span></dt>
<dd>The input file for <span class="Pa">sys/tools/vnode_if.awk</span>.</dd>
<dt><span class="Pa">sys/tools/vnode_if.awk</span></dt>
<dd>The script generating the source code of the
<code class="Fn">VOP_*</code>() functions.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">malloc(9)</a>, <a class="Xr">VFS(9)</a>,
<a class="Xr">VOP_ACCESS(9)</a>, <a class="Xr">VOP_ACLCHECK(9)</a>,
<a class="Xr">VOP_ADVISE(9)</a>, <a class="Xr">VOP_ADVLOCK(9)</a>,
<a class="Xr">VOP_ALLOCATE(9)</a>, <a class="Xr">VOP_ATTRIB(9)</a>,
<a class="Xr">VOP_BWRITE(9)</a>, <a class="Xr">VOP_CREATE(9)</a>,
<a class="Xr">VOP_FSYNC(9)</a>, <a class="Xr">VOP_GETACL(9)</a>,
<a class="Xr">VOP_GETEXTATTR(9)</a>, <a class="Xr">VOP_GETPAGES(9)</a>,
<a class="Xr">VOP_INACTIVE(9)</a>, <a class="Xr">VOP_IOCTL(9)</a>,
<a class="Xr">VOP_LINK(9)</a>, <a class="Xr">VOP_LISTEXTATTR(9)</a>,
<a class="Xr">VOP_LOCK(9)</a>, <a class="Xr">VOP_LOOKUP(9)</a>,
<a class="Xr">VOP_OPENCLOSE(9)</a>, <a class="Xr">VOP_PATHCONF(9)</a>,
<a class="Xr">VOP_PRINT(9)</a>, <a class="Xr">VOP_RDWR(9)</a>,
<a class="Xr">VOP_READ_PGCACHE(9)</a>, <a class="Xr">VOP_READDIR(9)</a>,
<a class="Xr">VOP_READLINK(9)</a>, <a class="Xr">VOP_REALLOCBLKS(9)</a>,
<a class="Xr">VOP_REMOVE(9)</a>, <a class="Xr">VOP_RENAME(9)</a>,
<a class="Xr">VOP_REVOKE(9)</a>, <a class="Xr">VOP_SETACL(9)</a>,
<a class="Xr">VOP_SETEXTATTR(9)</a>, <a class="Xr">VOP_SETLABEL(9)</a>,
<a class="Xr">VOP_STRATEGY(9)</a>, <a class="Xr">VOP_VPTOCNP(9)</a>,
<a class="Xr">VOP_VPTOFH(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">This manual page was written by <span class="An">Doug
Rabson</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">July 15, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
