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.4 2003/07/28 07:27:38 hmp 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 or directory
  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 three reference counts,
  51 .Va v_usecount ,
  52 .Va v_holdcnt
  53 and
  54 .Va v_writecount .
  55 The first is the number of clients within the kernel which are
  56 using this vnode.  This count is maintained by
  57 .Xr vref 9 ,
  58 .Xr vrele 9
  59 and
  60 .Xr vput 9 .
  61 The second is the number of clients within the kernel who veto
  62 the recycling of this vnode.  This count is
  63 maintained by
  64 .Xr vhold 9
  65 and
  66 .Xr vdrop 9 .
  67 When both the
  68 .Va v_usecount
  69 and the
  70 .Va v_holdcnt
  71 of a vnode reaches zero then the vnode will be put on the freelist
  72 and may be reused for another file, possibly in another filesystem.
  73 The transition to and from the freelist is handled by
  74 .Xr getnewvnode 9 ,
  75 .Xr vfree 9
  76 and
  77 .Xr vbusy 9 .
  78 The third is a count of the number of clients which are writing into
  79 the file.  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.  When the caller is finished with the vnode, it
  92 should release this reference by calling
  93 .Xr vrele 9
  94 (or
  95 .Xr vput 9
  96 if the vnode is locked).
  97 .Pp
  98 Other commonly used members of the vnode structure are
  99 .Va v_id
 100 which is used to maintain consistency in the name cache,
 101 .Va v_mount
 102 which points at the filesystem which owns the vnode,
 103 .Va v_type
 104 which contains the type of object the vnode represents and
 105 .Va v_data
 106 which is used by filesystems to store filesystem specific data with
 107 the vnode.
 108 The
 109 .Va v_op
 110 field is used by the
 111 .Dv VOP_*
 112 macros to call functions in the filesystem which implement the vnode's
 113 functionality.
 114 .Sh VNODE TYPES
 115 .Bl -tag -width VSOCK
 116 .It Dv VNON
 117 No type.
 118 .It Dv VREG
 119 A regular file; may be with or without VM object backing.  If you want
 120 to make sure this get a backing object, call
 121 .Xr vfs_object_create 9 .
 122 .It Dv VDIR
 123 A directory.
 124 .It Dv VBLK
 125 A block device; may be with or without VM object backing.  If you want
 126 to make sure this get a backing object, call
 127 .Xr vfs_object_create 9 .
 128 .It Dv VCHR
 129 A character device.
 130 .It Dv VLNK
 131 A symbolic link.
 132 .It Dv VSOCK
 133 A socket.  Advisory locking won't work on this.
 134 .It Dv VFIFO
 135 A FIFO (named pipe).  Advisory locking won't work on this.
 136 .It Dv VBAD
 137 An old style bad sector map
 138 .El
 139 .Sh 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
 148 .Vt "struct fileops"
 149 is used at all, is an artifact of an incomplete integration of
 150 the VFS code into the kernel.
 151 .Sh SEE ALSO
 152 .Xr VFS 9
 153 .Sh AUTHORS
 154 This manual page was written by
 155 .An Doug Rabson .