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