share/man/man9/VOP_READ_PGCACHE.9

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