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