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/vget.9,v 1.5.2.1 2001/12/17 11:30:19 ru Exp $ 28.\" 29.Dd May 5, 2007 30.Dt VGET 9 31.Os 32.Sh NAME 33.Nm vget 34.Nd Acquire a primary reference, lock, and reactivate a vnode 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/vnode.h 38.Ft int 39.Fn vget "struct vnode *vp" "int lockflag" 40.Sh DESCRIPTION 41Acquire a primary reference to vnode and lock it, reactivating the vnode 42from the cache or free list if necessary. 43This kernel function must be used if the vnode in hand is 44not already known to be actively referenced, such as when obtaining 45the vnode pointer from a namecache or VM object structure. 46.Bl -tag -width ".Fa lockflag" 47.It Fa vp 48The vnode being acquired, typically obtained from some other system 49structure. 50.It Fa lockflag 51Must be 52.Dv LK_SHARED 53or 54.Dv LK_EXCLUSIVE . 55Passing 0 is illegal. 56.Dv LK_NOWAIT 57may be logically ORd in if you do not wish to block and can handle the 58additional error codes that might be returned. 59.El 60.Pp 61When not in use, vnodes are kept on a free list or marked as being cached. 62The vnodes still reference valid files but may be reused to refer to a 63new file at any time. 64Often, references to these vnodes are present in auxiliary structures 65related to the vnode, such as namecache entries and VM objects. 66.Pp 67When acquiring a vnode pointer from these auxiliary structures the 68.Nm 69function must be used to both reference and, if necessary, reactivate 70the vnode. The vnode will also be locked accordingly. 71.Sh RETURN VALUES 720 is returned on success, 73.Er ENOENT 74is returned if the vnode becomes unusable while 75.Nm 76is blocked trying to lock it, and other errors may be returned as well. 77.Er ENOENT 78is not typically considered to be a fatal error but simply an 79indication that the caller needs to relookup the vnode as related 80structures may be in the midst of being destroyed. 81.Sh SEE ALSO 82.Xr vdrop 9 , 83.Xr vhold 9 , 84.Xr vnode 9 , 85.Xr vn_lock 9 , 86.Xr vn_unlock 9 , 87.Xr vput 9 , 88.Xr vref 9 , 89.Xr vrele 9 90.Sh AUTHORS 91This manual page was written by 92.An Doug Rabson . 93