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.\" 29.Dd May 5, 2007 30.Dt VHOLD 9 31.Os 32.Sh NAME 33.Nm vhold , vdrop 34.Nd "Acquire/release an auxiliary reference on a vnode" 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/vnode.h 38.Ft void 39.Fn vhold "struct vnode *vp" 40.Ft void 41.Fn vdrop "struct vnode *vp" 42.Sh DESCRIPTION 43The 44.Fn vhold 45function acquires an auxiliary reference on a vnode by incrementing the 46.Fa v_auxrefs 47field. 48Auxiliary references do not reactivate a vnode or move it to the cache 49if it resides on the free list, but they will prevent the vnode from 50being recycled (if not already being recycled), or reused. 51Auxiliary references are used to associate auxiliary structures such as 52namecache records with the vnode for those cases where the intent is to 53not allow the vnode to be immediately recycled. 54Auxiliary references are also used to access a vnode via an auxiliary 55structure without having to hold a deep stack of locks that might 56create deadlock issues for the caller. 57.Pp 58The 59.Fn vdrop 60function decrements the 61.Fa v_auxrefs 62field. If the vnode has been deactivated and resides in the cache, 63it will be moved to the free list when 64.Fa v_auxrefs 65drops to 0. 66.Sh SEE ALSO 67.Xr vget 9 , 68.Xr vnode 9 , 69.Xr vn_lock 9 , 70.Xr vn_unlock 9 , 71.Xr vput 9 , 72.Xr vref 9 , 73.Xr vrele 9 74.Sh AUTHORS 75This manual page was written by 76.An Chad David Aq Mt davidc@acns.ab.ca . 77