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