xref: /dflybsd-src/share/man/man9/vnode.9 (revision a706b3b1e6913c93163c4e7650a27ba2807808d2) 
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: src/share/man/man9/vnode.9,v 1.10.2.5 2001/12/17 11:30:19 ru Exp $
28.\" $DragonFly: src/share/man/man9/vnode.9,v 1.6 2007/05/05 06:26:57 dillon Exp $
29.\"
30.Dd June 28, 2003
31.Os
32.Dt VNODE 9
33.Sh NAME
34.Nm vnode
35.Nd internal representation of a file, directory, or other VFS entity
36.Sh SYNOPSIS
37.In sys/param.h
38.In sys/vnode.h
39.Sh DESCRIPTION
40The vnode is the focus of all file activity in
41.Ux .
42The
43.Nm
44is described by
45.Vt "struct vnode" .
46There is a
47unique vnode allocated for each active file, each current directory,
48each mounted-on file, text file, and the root.
49.Pp
50Each vnode has numerous reference counts,
51.Va v_sysref ,
52.Va v_auxrefs ,
53.Va v_opencount ,
54and
55.Va v_writecount .
56.Pp
57.Va v_sysref
58represents the number of primary references to the vnode.  It is actually
59a structure which utilizes the SYSREF API and also manages allocation and
60deallocation of the vnode.
61Primary references keep a vnode ready for I/O and prevent it from being
62deactivated.
63Primary references are managed by
64.Xr vref 9
65and
66.Xr vrele 9 .
67.Pp
68.Va v_auxrefs
69represents the number of auxiliary references to a vnode.  Auxiliary
70references prevent a vnode from being reclaimed (if not already being
71reclaimed), reused for other purposes, or otherwise destroyed, but
72do not activate or deactivate the vnode.
73Auxiliary references are managed by
74.Xr vhold 9
75and
76.Xr vdrop 9 .
77.Pp
78.Va v_opencount
79represents the number of discrete
80.Fn open
81calls made on the vnode (reading or writing).
82.Va v_writecount
83represents the number of descrete
84.Fn open
85calls made on the vnode for the purpose of writing.  This field
86will be a subset of
87.Va v_opencount .
88These fields are managed primarily by calls to
89.Xr vn_open 9
90and
91.Xr vn_close 9 .
92.Pp
93A deactivated vnode or a vnode in an unknown state accessed from an
94Auxiliary data structure can be reactivated, referenced, and locked using
95.Xr vget 9
96and
97.Xr vput 9 .
98.Pp
99An actively referenced and possibly locked vnode must be passed
100to most kernel procedures taking a vnode as an argument.
101Most kernel procedures returning a vnode will return one that is actively
102referenced.
103.Pp
104Other commonly used members of the vnode structure are
105.Va v_mount
106which points at the filesystem which owns the vnode,
107.Va v_type
108which contains the type of object the vnode represents and
109.Va v_data
110which is used by filesystems to store filesystem specific data with
111the vnode.
112The
113.Va v_ops
114field is used by the
115.Dv VOP_*
116macros to call functions in the filesystem which implement the vnode's
117functionality.
118.Sh VNODE TYPES
119.Bl -tag -width ".Fa VSOCK"
120.It Dv VNON
121No type.
122.It Dv VREG
123A regular file; may be with or without VM object backing.  If you want
124to make sure this get a backing object, call
125.Xr vfs_object_create 9 .
126.It Dv VDIR
127A directory.
128.It Dv VBLK
129A block device; may be with or without VM object backing.  If you want
130to make sure this get a backing object, call
131.Xr vfs_object_create 9 .
132.It Dv VCHR
133A character device.
134.It Dv VLNK
135A symbolic link.
136.It Dv VSOCK
137A socket.  Advisory locking won't work on this.
138.It Dv VFIFO
139A FIFO (named pipe).  Advisory locking won't work on this.
140.It Dv VBAD
141An old style bad sector map
142.El
143.Sh IMPLEMENTATION NOTES
144VFIFO uses the "struct fileops" from
145.Pa /sys/kern/sys_pipe.c .
146VSOCK uses the "struct fileops" from
147.Pa /sys/kern/sys_socket.c .
148Everything else uses the one from
149.Pa /sys/kern/vfs_vnops.c .
150.Pp
151The VFIFO/VSOCK code, which is why
152.Vt "struct fileops"
153is used at all, is an artifact of an incomplete integration of
154the VFS code into the kernel.
155.Sh SEE ALSO
156.Xr VFS 9
157.Sh AUTHORS
158This manual page was written by
159.An Doug Rabson .
160