share/man/man9/VOP_READ_PGCACHE.9

   1 .\" Copyright (c) 2021 The FreeBSD Foundation, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This documentation was written by
   5 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
   6 .\" from the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd February 28, 2021
  32 .Dt VOP_READ_PGCACHE 9
  33 .Os
  34 .Sh NAME
  35 .Nm VOP_READ_PGCACHE
  36 .Nd read a file, fast
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/vnode.h
  40 .In sys/uio.h
  41 .Ft int
  42 .Fo VOP_READ_PGCACHE
  43 .Fa "struct vnode *vp"
  44 .Fa "struct uio *uio"
  45 .Fa "int ioflag"
  46 .Fa "struct ucred *cred"
  47 .Fc
  48 .Sh DESCRIPTION
  49 This entry point reads the contents of a file.
  50 The intent is to provide the data from caches, which do not require
  51 expensive operations or any disk IO.
  52 For instance, if filesystem uses normal VM page cache and maintains
  53 .Dv v_object
  54 lifetime, it can use
  55 .Xr vn_read_from_obj 9
  56 helper to return data from the resident
  57 .Dv vp->v_object
  58 pages.
  59 .Pp
  60 The filesystem indicates support for the
  61 .Nm
  62 on specific vnode by setting the
  63 .Dv VIRF_PGREAD
  64 flag in
  65 .Dv vp->v_irflag .
  66 .Pp
  67 The function does not need to satisfy the whole request; it also might choose
  68 to not provide any data.
  69 In these cases, the
  70 .Fa uio
  71 must be advanced by the amount of read data,
  72 .Nm
  73 should return
  74 .Er EJUSTRETURN ,
  75 and VFS would handle the rest of the read operation using the
  76 .Xr VOP_READ 9 .
  77 .Pp
  78 The VFS layer does the same deadlock avoidance for accessing userspace
  79 pages from
  80 .Nm
  81 as for
  82 .Xr VOP_READ 9 .
  83 .Pp
  84 Vnode is not locked on the call entry and should not be locked on return.
  85 For a filesystem that requires vnode lock to return any data, it does
  86 not make sense to implement
  87 .Nm
  88 (and set
  89 .Dv VIRF_PGREAD
  90 flag) since VFS arranges the call to
  91 .Xr VOP_READ 9
  92 as needed.
  93 .Pp
  94 The arguments are:
  95 .Bl -tag -width ioflag
  96 .It Fa vp
  97 The vnode of the file.
  98 .It Fa uio
  99 The location of the data to be read.
 100 .It Fa ioflag
 101 Various flags, see
 102 .Xr VOP_READ 9
 103 for the list.
 104 .It Fa cred
 105 The credentials of the caller.
 106 .El
 107 .Pp
 108 .Nm
 109 does not handle non-zero
 110 .Fa ioflag
 111 argument.
 112 .Sh LOCKS
 113 The file should be referenced on entry on entry and will still be
 114 referenced on exit.
 115 Rangelock covering the whole read range should be owned around the call.
 116 .Sh RETURN VALUES
 117 Zero is returned on success, when the whole request is satisfied, and no
 118 more data cannot be provided for it by any means.
 119 If more data can be returned, but
 120 .Nm
 121 was unable to provide it,
 122 .Er EJUSTRETURN
 123 must be returned.
 124 The
 125 .Dv uio
 126 records should be updated according to the partial operation done.
 127 .Pp
 128 Otherwise an error code is returned,
 129 same as from
 130 .Xr VOP_READ 9
 131 .Sh SEE ALSO
 132 .Xr uiomove 9 ,
 133 .Xr vnode 9 ,
 134 .Xr VOP_READ 9