share/man/man9/vhold.9

   1 .\"
   2 .\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  18 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  25 .\" DAMAGE.
  26 .\"
  27 .\" $FreeBSD: src/share/man/man9/vhold.9,v 1.4 2005/07/22 00:28:22 rodrigc Exp $
  28 .\" $DragonFly: src/share/man/man9/vhold.9,v 1.4 2007/05/11 08:25:24 swildner Exp $
  29 .\"
  30 .Dd May 5, 2007
  31 .Dt VHOLD 9
  32 .Os
  33 .Sh NAME
  34 .Nm vhold , vdrop
  35 .Nd "Acquire/release an auxiliary reference on a vnode"
  36 .Sh SYNOPSIS
  37 .In sys/param.h
  38 .In sys/vnode.h
  39 .Ft void
  40 .Fn vhold "struct vnode *vp"
  41 .Ft void
  42 .Fn vdrop "struct vnode *vp"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn vhold
  46 function acquires an auxiliary reference on a vnode by incrementing the
  47 .Fa v_auxrefs
  48 field.
  49 Auxiliary references do not reactivate a vnode or move it to the cache
  50 if it resides on the free list, but they will prevent the vnode from
  51 being recycled (if not already being recycled), or reused.
  52 Auxiliary references are used to associate auxiliary structures such as
  53 namecache records with the vnode for those cases where the intent is to
  54 not allow the vnode to be immediately recycled.
  55 Auxiliary references are also used to access a vnode via an auxiliary
  56 structure without having to hold a deep stack of locks that might
  57 create deadlock issues for the caller.
  58 .Pp
  59 The
  60 .Fn vdrop
  61 function decrements the
  62 .Fa v_auxrefs
  63 field.  If the vnode has been deactivated and resides in the cache,
  64 it will be moved to the free list when
  65 .Fa v_auxrefs
  66 drops to 0.
  67 .Sh SEE ALSO
  68 .Xr vnode 9 ,
  69 .Xr vn_lock 9 ,
  70 .Xr vn_unlock 9 ,
  71 .Xr vget 9 ,
  72 .Xr vput 9 ,
  73 .Xr vref 9 ,
  74 .Xr vrele 9
  75 .Sh AUTHORS
  76 This manual page was written by
  77 .An Chad David Aq davidc@acns.ab.ca .