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$
  28 .\"
  29 .Dd May 20, 2003
  30 .Os
  31 .Dt VNODE 9
  32 .Sh NAME
  33 .Nm vnode
  34 .Nd internal representation of a file or directory
  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 A vnode is described by
  42 .Vt "struct vnode" .
  43 There is a
  44 unique vnode allocated for each active file, each current directory,
  45 each mounted-on file, text file, and the root.
  46 .Pp
  47 Each vnode has three reference counts,
  48 .Va v_usecount ,
  49 .Va v_holdcnt
  50 and
  51 .Va v_writecount .
  52 The first is the number of clients within the kernel which are
  53 using this vnode.
  54 This count is maintained by
  55 .Xr vref 9 ,
  56 .Xr vrele 9
  57 and
  58 .Xr vput 9 .
  59 The second is the number of clients within the kernel who veto
  60 the recycling of this vnode.
  61 This count is
  62 maintained by
  63 .Xr vhold 9
  64 and
  65 .Xr vdrop 9 .
  66 When both the
  67 .Va v_usecount
  68 and the
  69 .Va v_holdcnt
  70 of a vnode reaches zero then the vnode will be put on the freelist
  71 and may be reused for another file, possibly in another file system.
  72 The transition to and from the freelist is handled by
  73 .Xr getnewvnode 9 ,
  74 .Xr vfree 9
  75 and
  76 .Xr vbusy 9 .
  77 The third is a count of the number of clients which are writing into
  78 the file.
  79 It is maintained by the
  80 .Xr open 2
  81 and
  82 .Xr close 2
  83 system calls.
  84 .Pp
  85 Any call which returns a vnode (e.g.\&
  86 .Xr vget 9 ,
  87 .Xr VOP_LOOKUP 9
  88 etc.)
  89 will increase the
  90 .Va v_usecount
  91 of the vnode by one.
  92 When the caller is finished with the vnode, it
  93 should release this reference by calling
  94 .Xr vrele 9
  95 (or
  96 .Xr vput 9
  97 if the vnode is locked).
  98 .Pp
  99 Other commonly used members of the vnode structure are
 100 .Va v_id
 101 which is used to maintain consistency in the name cache,
 102 .Va v_mount
 103 which points at the file system which owns the vnode,
 104 .Va v_type
 105 which contains the type of object the vnode represents and
 106 .Va v_data
 107 which is used by file systems to store file system specific data with
 108 the vnode.
 109 The
 110 .Va v_op
 111 field is used by the
 112 .Dv VOP_*
 113 macros to call functions in the file system which implement the vnode's
 114 functionality.
 115 .Sh VNODE TYPES
 116 .Bl -tag -width VSOCK
 117 .It Dv VNON
 118 No type.
 119 .It Dv VREG
 120 A regular file; may be with or without VM object backing.
 121 If you want to make sure this get a backing object, call
 122 .Xr vfs_object_create 9 .
 123 .It Dv VDIR
 124 A directory.
 125 .It Dv VBLK
 126 A block device; may be with or without VM object backing.
 127 If you want to make sure this get a backing object, call
 128 .Xr vfs_object_create 9 .
 129 .It Dv VCHR
 130 A character device.
 131 .It Dv VLNK
 132 A symbolic link.
 133 .It Dv VSOCK
 134 A socket.
 135 Advisory locking will not work on this.
 136 .It Dv VFIFO
 137 A FIFO (named pipe).
 138 Advisory locking will not work on this.
 139 .It Dv VBAD
 140 An old style bad sector map
 141 .El
 142 .Sh IMPLEMENTATION NOTES
 143 VFIFO uses the "struct fileops" from
 144 .Pa /sys/kern/sys_pipe.c .
 145 VSOCK uses the "struct fileops" from
 146 .Pa /sys/kern/sys_socket.c .
 147 Everything else uses the one from
 148 .Pa /sys/kern/vfs_vnops.c .
 149 .Pp
 150 The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is
 151 an artifact of an incomplete integration of the VFS code into the
 152 kernel.
 153 .Pp
 154 Calls to
 155 .Xr malloc 9
 156 or
 157 .Xr free 9
 158 when holding a
 159 .Nm
 160 interlock, will cause a LOR (Lock Order Reversal) due to the
 161 intertwining of VM Objects and Vnodes.
 162 .Sh SEE ALSO
 163 .Xr malloc 9 ,
 164 .Xr VFS 9
 165 .Sh AUTHORS
 166 This manual page was written by
 167 .An Doug Rabson .