share/man/man9/vget.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/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
  41 Acquire a primary reference to vnode and lock it, reactivating the vnode
  42 from the cache or free list if necessary.
  43 This kernel function must be used if the vnode in hand is
  44 not already known to be actively referenced, such as when obtaining
  45 the vnode pointer from a namecache or VM object structure.
  46 .Bl -tag -width ".Fa lockflag"
  47 .It Fa vp
  48 The vnode being acquired, typically obtained from some other system
  49 structure.
  50 .It Fa lockflag
  51 Must be
  52 .Dv LK_SHARED
  53 or
  54 .Dv LK_EXCLUSIVE .
  55 Passing 0 is illegal.
  56 .Dv LK_NOWAIT
  57 may be logically ORd in if you do not wish to block and can handle the
  58 additional error codes that might be returned.
  59 .El
  60 .Pp
  61 When not in use, vnodes are kept on a free list or marked as being cached.
  62 The vnodes still reference valid files but may be reused to refer to a
  63 new file at any time.
  64 Often, references to these vnodes are present in auxiliary structures
  65 related to the vnode, such as namecache entries and VM objects.
  66 .Pp
  67 When acquiring a vnode pointer from these auxiliary structures the
  68 .Nm
  69 function must be used to both reference and, if necessary, reactivate
  70 the vnode.  The vnode will also be locked accordingly.
  71 .Sh RETURN VALUES
  72 0 is returned on success,
  73 .Er ENOENT
  74 is returned if the vnode becomes unusable while
  75 .Nm
  76 is blocked trying to lock it, and other errors may be returned as well.
  77 .Er ENOENT
  78 is not typically considered to be a fatal error but simply an
  79 indication that the caller needs to relookup the vnode as related
  80 structures 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
  91 This manual page was written by
  92 .An Doug Rabson .