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