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 February 12, 2014
  30 .Dt VNODE 9
  31 .Os
  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 from the freelist is handled by
  73 .Xr getnewvnode 9 .
  74 The third is a count of the number of clients which are writing into
  75 the file.
  76 It is maintained by the
  77 .Xr open 2
  78 and
  79 .Xr close 2
  80 system calls.
  81 .Pp
  82 Any call which returns a vnode (e.g.,\&
  83 .Xr vget 9 ,
  84 .Xr VOP_LOOKUP 9 ,
  85 etc.)
  86 will increase the
  87 .Va v_usecount
  88 of the vnode by one.
  89 When the caller is finished with the vnode, it
  90 should release this reference by calling
  91 .Xr vrele 9
  92 (or
  93 .Xr vput 9
  94 if the vnode is locked).
  95 .Pp
  96 Other commonly used members of the vnode structure are
  97 .Va v_id
  98 which is used to maintain consistency in the name cache,
  99 .Va v_mount
 100 which points at the file system which owns the vnode,
 101 .Va v_type
 102 which contains the type of object the vnode represents and
 103 .Va v_data
 104 which is used by file systems to store file system specific data with
 105 the vnode.
 106 The
 107 .Va v_op
 108 field is used by the
 109 .Dv VOP_*
 110 macros to call functions in the file system which implement the vnode's
 111 functionality.
 112 .Sh VNODE TYPES
 113 .Bl -tag -width VSOCK
 114 .It Dv VNON
 115 No type.
 116 .It Dv VREG
 117 A regular file; may be with or without VM object backing.
 118 If you want to make sure this get a backing object, call
 119 .Fn vnode_create_vobject .
 120 .It Dv VDIR
 121 A directory.
 122 .It Dv VBLK
 123 A block device; may be with or without VM object backing.
 124 If you want to make sure this get a backing object, call
 125 .Fn vnode_create_vobject .
 126 .It Dv VCHR
 127 A character device.
 128 .It Dv VLNK
 129 A symbolic link.
 130 .It Dv VSOCK
 131 A socket.
 132 Advisory locking will not work on this.
 133 .It Dv VFIFO
 134 A FIFO (named pipe).
 135 Advisory locking will not work on this.
 136 .It Dv VBAD
 137 Indicates that the vnode has been reclaimed.
 138 .El
 139 .Sh IMPLEMENTATION NOTES
 140 VFIFO uses the "struct fileops" from
 141 .Pa /sys/kern/sys_pipe.c .
 142 VSOCK uses the "struct fileops" from
 143 .Pa /sys/kern/sys_socket.c .
 144 Everything else uses the one from
 145 .Pa /sys/kern/vfs_vnops.c .
 146 .Pp
 147 The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is
 148 an artifact of an incomplete integration of the VFS code into the
 149 kernel.
 150 .Pp
 151 Calls to
 152 .Xr malloc 9
 153 or
 154 .Xr free 9
 155 when holding a
 156 .Nm
 157 interlock, will cause a LOR (Lock Order Reversal) due to the
 158 intertwining of VM Objects and Vnodes.
 159 .Sh SEE ALSO
 160 .Xr malloc 9 ,
 161 .Xr VOP_ACCESS 9 ,
 162 .Xr VOP_ACLCHECK 9 ,
 163 .Xr VOP_ADVISE 9 ,
 164 .Xr VOP_ADVLOCK 9 ,
 165 .Xr VOP_ALLOCATE 9 ,
 166 .Xr VOP_ATTRIB 9 ,
 167 .Xr VOP_BWRITE 9 ,
 168 .Xr VOP_CREATE 9 ,
 169 .Xr VOP_FSYNC 9 ,
 170 .Xr VOP_GETACL 9 ,
 171 .Xr VOP_GETEXTATTR 9 ,
 172 .Xr VOP_GETPAGES 9 ,
 173 .Xr VOP_INACTIVE 9 ,
 174 .Xr VOP_IOCTL 9 ,
 175 .Xr VOP_LINK 9 ,
 176 .Xr VOP_LISTEXTATTR 9 ,
 177 .Xr VOP_LOCK 9 ,
 178 .Xr VOP_LOOKUP 9 ,
 179 .Xr VOP_OPENCLOSE 9 ,
 180 .Xr VOP_PATHCONF 9 ,
 181 .Xr VOP_PRINT 9 ,
 182 .Xr VOP_RDWR 9 ,
 183 .Xr VOP_READDIR 9 ,
 184 .Xr VOP_READLINK 9 ,
 185 .Xr VOP_REALLOCBLKS 9 ,
 186 .Xr VOP_REMOVE 9 ,
 187 .Xr VOP_RENAME 9 ,
 188 .Xr VOP_REVOKE 9 ,
 189 .Xr VOP_SETACL 9 ,
 190 .Xr VOP_SETEXTATTR 9 ,
 191 .Xr VOP_STRATEGY 9 ,
 192 .Xr VOP_VPTOCNP 9 ,
 193 .Xr VOP_VPTOFH 9 ,
 194 .Xr VFS 9
 195 .Sh AUTHORS
 196 This manual page was written by
 197 .An Doug Rabson .