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