share/man/man9/vnode.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 1996 Doug Rabson
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" This program is free software.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD: src/share/man/man9/vnode.9,v 1.10.2.5 2001/12/17 11:30:19 ru Exp $
  30 .\"
  31 .Dd June 30, 1999
  32 .Os
  33 .Dt VNODE 9
  34 .Sh NAME
  35 .Nm vnode
  36 .Nd internal representation of a file or directory
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/vnode.h
  40 .Pp
  41 .Bd -literal
  42 /*
  43  * Vnode types.  VNON means no type.
  44  */
  45 enum vtype      { VNON, VREG, VDIR, VBLK, VCHR, VLNK, VSOCK, VFIFO, VBAD };
  46
  47 /*
  48  * Vnode tag types.
  49  * These are for the benefit of external programs only (e.g., pstat)
  50  * and should NEVER be inspected by the kernel.
  51  */
  52 enum vtagtype   {
  53         VT_NON, VT_UFS, VT_NFS, VT_MFS, VT_PC, VT_LFS, VT_LOFS, VT_FDESC,
  54         VT_PORTAL, VT_NULL, VT_UMAP, VT_KERNFS, VT_PROCFS, VT_AFS, VT_ISOFS,
  55         VT_UNION, VT_MSDOSFS, VT_TFS, VT_VFS, VT_CODA, VT_NTFS
  56 };
  57
  58 /*
  59  * Each underlying filesystem allocates its own private area and hangs
  60  * it from v_data.  If non-null, this area is freed in getnewvnode().
  61  */
  62 TAILQ_HEAD(buflists, buf);
  63
  64 typedef int     vop_t __P((void *));
  65 struct namecache;
  66
  67 /*
  68  * Reading or writing any of these items requires holding the appropriate lock.
  69  * v_freelist is locked by the global vnode_free_list simple lock.
  70  * v_mntvnodes is locked by the global mntvnodes simple lock.
  71  * v_flag, v_usecount, v_holdcount and v_writecount are
  72  *    locked by the v_interlock simple lock.
  73  * v_pollinfo is locked by the lock contained inside it.
  74  */
  75 struct vnode {
  76         u_long  v_flag;                         /* vnode flags (see below) */
  77         int     v_usecount;                     /* reference count of users */
  78         int     v_writecount;                   /* reference count of writers */
  79         int     v_holdcnt;                      /* page & buffer references */
  80         daddr_t v_lastr;                        /* last read (read-ahead) */
  81         u_long  v_id;                           /* capability identifier */
  82         struct  mount *v_mount;                 /* ptr to vfs we are in */
  83         vop_t   **v_op;                         /* vnode operations vector */
  84         TAILQ_ENTRY(vnode) v_freelist;          /* vnode freelist */
  85         LIST_ENTRY(vnode) v_mntvnodes;          /* vnodes for mount point */
  86         struct  buflists v_cleanblkhd;          /* clean blocklist head */
  87         struct  buflists v_dirtyblkhd;          /* dirty blocklist head */
  88         LIST_ENTRY(vnode) v_synclist;           /* vnodes with dirty buffers */
  89         long    v_numoutput;                    /* num of writes in progress */
  90         enum    vtype v_type;                   /* vnode type */
  91         union {
  92                 struct mount    *vu_mountedhere;/* ptr to mounted vfs (VDIR) */
  93                 struct socket   *vu_socket;     /* unix ipc (VSOCK) */
  94                 struct specinfo *vu_specinfo;   /* device (VCHR, VBLK) */
  95                 struct fifoinfo *vu_fifoinfo;   /* fifo (VFIFO) */
  96         } v_un;
  97         struct  nqlease *v_lease;               /* Soft reference to lease */
  98         daddr_t v_lastw;                        /* last write (write cluster) */
  99         daddr_t v_cstart;                       /* start block of cluster */
 100         daddr_t v_lasta;                        /* last allocation */
 101         int     v_clen;                         /* length of current cluster */
 102         int     v_maxio;                        /* maximum I/O cluster size */
 103         struct vm_object *v_object;             /* Place to store VM object */
 104         struct  simplelock v_interlock;         /* lock on usecount and flag */
 105         struct  lock *v_vnlock;                 /* used for non-locking fs's */
 106         enum    vtagtype v_tag;                 /* type of underlying data */
 107         void    *v_data;                        /* private data for fs */
 108         LIST_HEAD(, namecache) v_cache_src;     /* Cache entries from us */
 109         TAILQ_HEAD(, namecache) v_cache_dst;    /* Cache entries to us */
 110         struct  vnode *v_dd;                    /* .. vnode */
 111         u_long  v_ddid;                         /* .. capability identifier */
 112         struct  {
 113                 struct  simplelock vpi_lock;    /* lock to protect below */
 114                 struct  selinfo vpi_selinfo;    /* identity of poller(s) */
 115                 short   vpi_events;             /* what they are looking for */
 116                 short   vpi_revents;            /* what has happened */
 117         } v_pollinfo;
 118 };
 119 #define v_mountedhere   v_un.vu_mountedhere
 120 #define v_socket        v_un.vu_socket
 121 #define v_specinfo      v_un.vu_specinfo
 122 #define v_fifoinfo      v_un.vu_fifoinfo
 123
 124 /*
 125  * Vnode flags.
 126  */
 127 #define VROOT           0x00001 /* root of its file system */
 128 #define VTEXT           0x00002 /* vnode is a pure text prototype */
 129 #define VSYSTEM         0x00004 /* vnode being used by kernel */
 130 #define VISTTY          0x00008 /* vnode represents a tty */
 131 #define VXLOCK          0x00100 /* vnode is locked to change underlying type */
 132 #define VXWANT          0x00200 /* process is waiting for vnode */
 133 #define VBWAIT          0x00400 /* waiting for output to complete */
 134 #define VALIASED        0x00800 /* vnode has an alias */
 135 #define VDIROP          0x01000 /* LFS: vnode is involved in a directory op */
 136 #define VOBJBUF         0x02000 /* Allocate buffers in VM object */
 137 #define VNINACT         0x04000 /* LFS: skip ufs_inactive() in lfs_vunref */
 138 #define VAGE            0x08000 /* Insert vnode at head of free list */
 139 #define VOLOCK          0x10000 /* vnode is locked waiting for an object */
 140 #define VOWANT          0x20000 /* a process is waiting for VOLOCK */
 141 #define VDOOMED         0x40000 /* This vnode is being recycled */
 142 #define VFREE           0x80000 /* This vnode is on the freelist */
 143 #define VTBFREE         0x100000 /* This vnode is on the to-be-freelist */
 144 #define VONWORKLST      0x200000 /* On syncer work-list */
 145 #define VMOUNT          0x400000 /* Mount in progress */
 146
 147 .Ed
 148 .Sh DESCRIPTION
 149 The vnode is the focus of all file activity in UNIX.  There is a
 150 unique vnode allocated for each active file, each current directory,
 151 each mounted-on file, text file, and the root.
 152 .Pp
 153 Each vnode has three reference counts,
 154 .Dv v_usecount ,
 155 .Dv v_holdcnt
 156 and
 157 .Dv v_writecount .
 158 The first is the number of clients within the kernel which are
 159 using this vnode.  This count is maintained by
 160 .Xr vref 9 ,
 161 .Xr vrele 9
 162 and
 163 .Xr vput 9 .
 164 The second is the number of clients within the kernel who veto
 165 the recycling of this vnode.  This count is
 166 maintained by
 167 .Xr vhold 9
 168 and
 169 .Xr vdrop 9 .
 170 When both the
 171 .Dv v_usecount
 172 and the
 173 .Dv v_holdcnt
 174 of a vnode reaches zero then the vnode will be put on the freelist
 175 and may be reused for another file, possibly in another filesystem.
 176 The transition to and from the freelist is handled by
 177 .Xr getnewvnode 9 ,
 178 .Xr vfree 9
 179 and
 180 .Xr vbusy 9 .
 181 The third is a count of the number of clients which are writing into
 182 the file.  It is maintained by the
 183 .Xr open 2
 184 and
 185 .Xr close 2
 186 system calls.
 187 .Pp
 188 Any call which returns a vnode (e.g.\&
 189 .Xr VFS_GET 9 ,
 190 .Xr VOP_LOOKUP 9
 191 etc.)
 192 will increase the
 193 .Dv v_usecount
 194 of the vnode by one.  When the caller is finished with the vnode, it
 195 should release this reference by calling
 196 .Xr vrele 9
 197 (or
 198 .Xr vput 9
 199 if the vnode is locked).
 200 .Pp
 201 Other commonly used members of the vnode structure are
 202 .Dv v_id
 203 which is used to maintain consistency in the name cache,
 204 .Dv v_mount
 205 which points at the filesystem which owns the vnode,
 206 .Dv v_type
 207 which contains the type of object the vnode represents and
 208 .Dv v_data
 209 which is used by filesystems to store filesystem specific data with
 210 the vnode.
 211 The
 212 .Dv v_op
 213 field is used by the
 214 .Dv VOP_*
 215 macros to call functions in the filesystem which implement the vnode's
 216 functionality.
 217 .Sh VNODE TYPES
 218 .Bl -tag -width VSOCK
 219 .It Dv VNON
 220 No type.
 221 .It Dv VREG
 222 A regular file; may be with or without VM object backing.  If you want
 223 to make sure this get a backing object, call
 224 .Xr vfs_object_create 9 .
 225 .It Dv VDIR
 226 A directory.
 227 .It Dv VBLK
 228 A block device; may be with or without VM object backing.  If you want
 229 to make sure this get a backing object, call
 230 .Xr vfs_object_create 9 .
 231 .It Dv VCHR
 232 A character device.
 233 .It Dv VLNK
 234 A symbolic link.
 235 .It Dv VSOCK
 236 A socket.  Advisory locking won't work on this.
 237 .It Dv VFIFO
 238 A FIFO (named pipe).  Advisory locking won't work on this.
 239 .It Dv VBAD
 240 An old style bad sector map
 241 .El
 242 .Sh NOTES
 243 VFIFO uses the "struct fileops" from
 244 .Pa /sys/kern/sys_pipe.c .
 245 VSOCK uses the "struct fileops" from
 246 .Pa /sys/kern/sys_socket.c .
 247 Everything else uses the one from
 248 .Pa /sys/kern/vfs_vnops.c .
 249 .Pp
 250 The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is
 251 an artifact of an incomplete integration of the VFS code into the
 252 kernel.
 253 .Sh SEE ALSO
 254 .Xr VFS 9
 255 .Sh AUTHORS
 256 This man page was written by
 257 .An Doug Rabson .