share/man/man9/vref.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/vref.9,v 1.6.2.2 2001/12/17 11:30:19 ru Exp $
  28 .\"
  29 .Dd May 5, 2007
  30 .Dt VREF 9
  31 .Os
  32 .Sh NAME
  33 .Nm vref
  34 .Nd Increment the primary reference count for an active vnode
  35 .Sh SYNOPSIS
  36 .In sys/param.h
  37 .In sys/vnode.h
  38 .Ft void
  39 .Fn vref "struct vnode *vp"
  40 .Sh DESCRIPTION
  41 The primary reference count for an active vnode is incremented.
  42 The vnode must already have active references to it, usually acquired
  43 prior to the vnode pointer being passed to the code making this call
  44 or when vnode pointers are obtained from structures, such as file pointers,
  45 which hold an active reference to the vnode.
  46 Any attempt to use
  47 .Nm
  48 on an inactive vnode will result in a panic.
  49 .Bl -tag -width ".Fa vp"
  50 .It Fa vp
  51 The vnode being referenced.
  52 .El
  53 .Pp
  54 Each vnode maintains a Primary and Auxiliary reference count.
  55 The primary reference count prevents the vnode from being deactivated
  56 while the auxiliary reference count keeps track of auxiliary structures,
  57 such as namecache and VM object structures, which are typically kept
  58 associated with the vnode for caching purposes even after the vnode
  59 has been deactivated.
  60 .Pp
  61 A procedure will often acquire its own primary reference to a vnode
  62 to prevent the vnode from getting ripped out from under it during
  63 an operation due to the destruction of the parent data structure.
  64 For example, one thread may be blocked on a vnode operation related
  65 to a file descriptor that another thread then closes.
  66 .Sh SEE ALSO
  67 .Xr vdrop 9 ,
  68 .Xr vget 9 ,
  69 .Xr vhold 9 ,
  70 .Xr vnode 9 ,
  71 .Xr vn_lock 9 ,
  72 .Xr vn_unlock 9 ,
  73 .Xr vput 9 ,
  74 .Xr vrele 9
  75 .Sh AUTHORS
  76 This manual page was written by
  77 .An Doug Rabson .