1.\" -*- nroff -*-
2.\"
3.\" Copyright (c) 1996 Doug Rabson
4.\"
5.\" All rights reserved.
6.\"
7.\" This program is free software.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28.\"
| 1.\" -*- nroff -*-
2.\"
3.\" Copyright (c) 1996 Doug Rabson
4.\"
5.\" All rights reserved.
6.\"
7.\" This program is free software.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28.\"
|
30.\"
31.Dd July 24, 1996
32.Os
33.Dt VNODE 9
34.Sh NAME
35.Nm vnode
36.Nd internal representation of a file or directory
37.Sh SYNOPSIS
38.Fd #include <sys/param.h>
39.Fd #include <sys/vnode.h>
40.Pp
41.Bd -literal
42/*
43 * Vnode types. VNON means no type.
44 */
45enum vtype { VNON, VREG, VDIR, VBLK, VCHR, VLNK, VSOCK, VFIFO, VBAD };
46
47/*
48 * Vnode tag types.
49 * These are for the benefit of external programs only (e.g., pstat)
50 * and should NEVER be inspected by the kernel.
51 */
52enum vtagtype {
53 VT_NON, VT_UFS, VT_NFS, VT_MFS, VT_PC, VT_LFS, VT_LOFS, VT_FDESC,
54 VT_PORTAL, VT_NULL, VT_UMAP, VT_KERNFS, VT_PROCFS, VT_AFS, VT_ISOFS,
55 VT_UNION, VT_MSDOSFS, VT_DEVFS
56};
57
58/*
59 * Each underlying filesystem allocates its own private area and hangs
60 * it from v_data. If non-null, this area is freed in getnewvnode().
61 */
62LIST_HEAD(buflists, buf);
63
64typedef int vop_t __P((void *));
65
66struct vnode {
67 u_long v_flag; /* vnode flags (see below) */
68 int v_usecount; /* reference count of users */
69 int v_writecount; /* reference count of writers */
70 int v_holdcnt; /* page & buffer references */
71 daddr_t v_lastr; /* last read (read-ahead) */
72 u_long v_id; /* capability identifier */
73 struct mount *v_mount; /* ptr to vfs we are in */
74 vop_t **v_op; /* vnode operations vector */
75 TAILQ_ENTRY(vnode) v_freelist; /* vnode freelist */
76 LIST_ENTRY(vnode) v_mntvnodes; /* vnodes for mount point */
77 struct buflists v_cleanblkhd; /* clean blocklist head */
78 struct buflists v_dirtyblkhd; /* dirty blocklist head */
79 long v_numoutput; /* num of writes in progress */
80 enum vtype v_type; /* vnode type */
81 union {
82 struct mount *vu_mountedhere;/* ptr to mounted vfs (VDIR) */
83 struct socket *vu_socket; /* unix ipc (VSOCK) */
84 struct specinfo *vu_specinfo; /* device (VCHR, VBLK) */
85 struct fifoinfo *vu_fifoinfo; /* fifo (VFIFO) */
86 } v_un;
87 struct nqlease *v_lease; /* Soft reference to lease */
88 daddr_t v_lastw; /* last write (write cluster) */
89 daddr_t v_cstart; /* start block of cluster */
90 daddr_t v_lasta; /* last allocation */
91 int v_clen; /* length of current cluster */
92 int v_ralen; /* Read-ahead length */
93 int v_usage; /* Vnode usage counter */
94 daddr_t v_maxra; /* last readahead block */
95 void *v_object; /* Place to store VM object */
96 enum vtagtype v_tag; /* type of underlying data */
97 void *v_data; /* private data for fs */
98};
99#define v_mountedhere v_un.vu_mountedhere
100#define v_socket v_un.vu_socket
101#define v_specinfo v_un.vu_specinfo
102#define v_fifoinfo v_un.vu_fifoinfo
103
104/*
105 * Vnode flags.
106 */
107#define VROOT 0x00001 /* root of its file system */
108#define VTEXT 0x00002 /* vnode is a pure text prototype */
109#define VSYSTEM 0x00004 /* vnode being used by kernel */
110#define VOLOCK 0x00008 /* vnode is locked waiting for an object */
111#define VOWANT 0x00010 /* a process is waiting for VOLOCK */
112#define VXLOCK 0x00100 /* vnode is locked to change underlying type */
113#define VXWANT 0x00200 /* process is waiting for vnode */
114#define VBWAIT 0x00400 /* waiting for output to complete */
115#define VALIASED 0x00800 /* vnode has an alias */
116#define VDIROP 0x01000 /* LFS: vnode is involved in a directory op */
117#define VVMIO 0x02000 /* VMIO flag */
118#define VNINACT 0x04000 /* LFS: skip ufs_inactive() in lfs_vunref */
119#define VAGE 0x08000 /* Insert vnode at head of free list */
120#define VOLOCK 0x10000 /* vnode is locked waiting for an object */
121#define VOWANT 0x20000 /* a process is waiting for VOLOCK */
122#define VDOOMED 0x40000 /* This vnode is being recycled */
123#define VFREE 0x80000 /* This vnode is on the freelist */
124
125
126.Ed
127.Sh DESCRIPTION
128The vnode is the focus of all file activity in UNIX. There is a
129unique vnode allocated for each active file, each current directory,
130each mounted-on file, text file, and the root.
131.Pp
132Each vnode has three reference counts,
133.Dv v_usecount ,
134.Dv v_holdcnt
135and
136.Dv v_writecount .
137The first is the number of clients within the kernel which are
138using this vnode. This count is maintained by
139.Xr vref 9 ,
140.Xr vrele 9
141and
142.Xr vput 9 .
143The second is the number of clients within the kernel who veto
144the recycling of this vnode. This count is
145maintained by
146.Xr vhold 9
147and
148.Xr vdrop 9 .
149When both the
150.Dv v_usecount
151and the
152.Dv v_holdcnt
153of a vnode reaches zero then the vnode will be put on the freelist
154and may be reused for another file, possibly in another filesystem.
155The transition to and from the freelist is handled by
156.Xr getnetvnode 9 ,
157.Xr vfree 9
158and
159.Xr vbusy 9 .
160The third is a count of the number of clients which are writing into
161the file. It is maintained by the
162.Xr open 2
163and
164.Xr close 2
165system calls.
166.Pp
167Any call which returns a vnode (e.g.
168.Xr VFS_GET 9 ,
169.Xr VOP_LOOKUP 9
170etc.)
171will increase the
172.Dv v_usecount
173of the vnode by one. When the caller is finished with the vnode, it
174should release this reference by calling
175.Xr vrele 9
176(or
177.Xr vput 9
178if the vnode is locked).
179.Pp
180Other commonly used members of the vnode structure are
181.Dv v_id
182which is used to maintain consistency in the name cache,
183.Dv v_mount
184which points at the filesystem which owns the vnode,
185.Dv v_type
186which contains the type of object the vnode represents and
187.Dv v_data
188which is used by filesystems to store filesystem specific data with
189the vnode.
190The
191.Dv v_op
192field is used by the
193.Dv VOP_*
194macros to call functions in the filesystem which implement the vnode's
195functionality.
196.Sh SEE ALSO
197.Xr VFS 9
198.Sh AUTHORS
| 30.\"
31.Dd July 24, 1996
32.Os
33.Dt VNODE 9
34.Sh NAME
35.Nm vnode
36.Nd internal representation of a file or directory
37.Sh SYNOPSIS
38.Fd #include <sys/param.h>
39.Fd #include <sys/vnode.h>
40.Pp
41.Bd -literal
42/*
43 * Vnode types. VNON means no type.
44 */
45enum vtype { VNON, VREG, VDIR, VBLK, VCHR, VLNK, VSOCK, VFIFO, VBAD };
46
47/*
48 * Vnode tag types.
49 * These are for the benefit of external programs only (e.g., pstat)
50 * and should NEVER be inspected by the kernel.
51 */
52enum vtagtype {
53 VT_NON, VT_UFS, VT_NFS, VT_MFS, VT_PC, VT_LFS, VT_LOFS, VT_FDESC,
54 VT_PORTAL, VT_NULL, VT_UMAP, VT_KERNFS, VT_PROCFS, VT_AFS, VT_ISOFS,
55 VT_UNION, VT_MSDOSFS, VT_DEVFS
56};
57
58/*
59 * Each underlying filesystem allocates its own private area and hangs
60 * it from v_data. If non-null, this area is freed in getnewvnode().
61 */
62LIST_HEAD(buflists, buf);
63
64typedef int vop_t __P((void *));
65
66struct vnode {
67 u_long v_flag; /* vnode flags (see below) */
68 int v_usecount; /* reference count of users */
69 int v_writecount; /* reference count of writers */
70 int v_holdcnt; /* page & buffer references */
71 daddr_t v_lastr; /* last read (read-ahead) */
72 u_long v_id; /* capability identifier */
73 struct mount *v_mount; /* ptr to vfs we are in */
74 vop_t **v_op; /* vnode operations vector */
75 TAILQ_ENTRY(vnode) v_freelist; /* vnode freelist */
76 LIST_ENTRY(vnode) v_mntvnodes; /* vnodes for mount point */
77 struct buflists v_cleanblkhd; /* clean blocklist head */
78 struct buflists v_dirtyblkhd; /* dirty blocklist head */
79 long v_numoutput; /* num of writes in progress */
80 enum vtype v_type; /* vnode type */
81 union {
82 struct mount *vu_mountedhere;/* ptr to mounted vfs (VDIR) */
83 struct socket *vu_socket; /* unix ipc (VSOCK) */
84 struct specinfo *vu_specinfo; /* device (VCHR, VBLK) */
85 struct fifoinfo *vu_fifoinfo; /* fifo (VFIFO) */
86 } v_un;
87 struct nqlease *v_lease; /* Soft reference to lease */
88 daddr_t v_lastw; /* last write (write cluster) */
89 daddr_t v_cstart; /* start block of cluster */
90 daddr_t v_lasta; /* last allocation */
91 int v_clen; /* length of current cluster */
92 int v_ralen; /* Read-ahead length */
93 int v_usage; /* Vnode usage counter */
94 daddr_t v_maxra; /* last readahead block */
95 void *v_object; /* Place to store VM object */
96 enum vtagtype v_tag; /* type of underlying data */
97 void *v_data; /* private data for fs */
98};
99#define v_mountedhere v_un.vu_mountedhere
100#define v_socket v_un.vu_socket
101#define v_specinfo v_un.vu_specinfo
102#define v_fifoinfo v_un.vu_fifoinfo
103
104/*
105 * Vnode flags.
106 */
107#define VROOT 0x00001 /* root of its file system */
108#define VTEXT 0x00002 /* vnode is a pure text prototype */
109#define VSYSTEM 0x00004 /* vnode being used by kernel */
110#define VOLOCK 0x00008 /* vnode is locked waiting for an object */
111#define VOWANT 0x00010 /* a process is waiting for VOLOCK */
112#define VXLOCK 0x00100 /* vnode is locked to change underlying type */
113#define VXWANT 0x00200 /* process is waiting for vnode */
114#define VBWAIT 0x00400 /* waiting for output to complete */
115#define VALIASED 0x00800 /* vnode has an alias */
116#define VDIROP 0x01000 /* LFS: vnode is involved in a directory op */
117#define VVMIO 0x02000 /* VMIO flag */
118#define VNINACT 0x04000 /* LFS: skip ufs_inactive() in lfs_vunref */
119#define VAGE 0x08000 /* Insert vnode at head of free list */
120#define VOLOCK 0x10000 /* vnode is locked waiting for an object */
121#define VOWANT 0x20000 /* a process is waiting for VOLOCK */
122#define VDOOMED 0x40000 /* This vnode is being recycled */
123#define VFREE 0x80000 /* This vnode is on the freelist */
124
125
126.Ed
127.Sh DESCRIPTION
128The vnode is the focus of all file activity in UNIX. There is a
129unique vnode allocated for each active file, each current directory,
130each mounted-on file, text file, and the root.
131.Pp
132Each vnode has three reference counts,
133.Dv v_usecount ,
134.Dv v_holdcnt
135and
136.Dv v_writecount .
137The first is the number of clients within the kernel which are
138using this vnode. This count is maintained by
139.Xr vref 9 ,
140.Xr vrele 9
141and
142.Xr vput 9 .
143The second is the number of clients within the kernel who veto
144the recycling of this vnode. This count is
145maintained by
146.Xr vhold 9
147and
148.Xr vdrop 9 .
149When both the
150.Dv v_usecount
151and the
152.Dv v_holdcnt
153of a vnode reaches zero then the vnode will be put on the freelist
154and may be reused for another file, possibly in another filesystem.
155The transition to and from the freelist is handled by
156.Xr getnetvnode 9 ,
157.Xr vfree 9
158and
159.Xr vbusy 9 .
160The third is a count of the number of clients which are writing into
161the file. It is maintained by the
162.Xr open 2
163and
164.Xr close 2
165system calls.
166.Pp
167Any call which returns a vnode (e.g.
168.Xr VFS_GET 9 ,
169.Xr VOP_LOOKUP 9
170etc.)
171will increase the
172.Dv v_usecount
173of the vnode by one. When the caller is finished with the vnode, it
174should release this reference by calling
175.Xr vrele 9
176(or
177.Xr vput 9
178if the vnode is locked).
179.Pp
180Other commonly used members of the vnode structure are
181.Dv v_id
182which is used to maintain consistency in the name cache,
183.Dv v_mount
184which points at the filesystem which owns the vnode,
185.Dv v_type
186which contains the type of object the vnode represents and
187.Dv v_data
188which is used by filesystems to store filesystem specific data with
189the vnode.
190The
191.Dv v_op
192field is used by the
193.Dv VOP_*
194macros to call functions in the filesystem which implement the vnode's
195functionality.
196.Sh SEE ALSO
197.Xr VFS 9
198.Sh AUTHORS
|