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 .Dd February 28, 2021
  29 .Dt VOP_READ_PGCACHE 9
  30 .Os
  31 .Sh NAME
  32 .Nm VOP_READ_PGCACHE
  33 .Nd read a file, fast
  34 .Sh SYNOPSIS
  35 .In sys/param.h
  36 .In sys/vnode.h
  37 .In sys/uio.h
  38 .Ft int
  39 .Fo VOP_READ_PGCACHE
  40 .Fa "struct vnode *vp"
  41 .Fa "struct uio *uio"
  42 .Fa "int ioflag"
  43 .Fa "struct ucred *cred"
  44 .Fc
  45 .Sh DESCRIPTION
  46 This entry point reads the contents of a file.
  47 The intent is to provide the data from caches, which do not require
  48 expensive operations or any disk IO.
  49 For instance, if filesystem uses normal VM page cache and maintains
  50 .Dv v_object
  51 lifetime, it can use
  52 .Xr vn_read_from_obj 9
  53 helper to return data from the resident
  54 .Dv vp->v_object
  55 pages.
  56 .Pp
  57 The filesystem indicates support for the
  58 .Nm
  59 on specific vnode by setting the
  60 .Dv VIRF_PGREAD
  61 flag in
  62 .Dv vp->v_irflag .
  63 .Pp
  64 The function does not need to satisfy the whole request; it also might choose
  65 to not provide any data.
  66 In these cases, the
  67 .Fa uio
  68 must be advanced by the amount of read data,
  69 .Nm
  70 should return
  71 .Er EJUSTRETURN ,
  72 and VFS would handle the rest of the read operation using the
  73 .Xr VOP_READ 9 .
  74 .Pp
  75 The VFS layer does the same deadlock avoidance for accessing userspace
  76 pages from
  77 .Nm
  78 as for
  79 .Xr VOP_READ 9 .
  80 .Pp
  81 Vnode is not locked on the call entry and should not be locked on return.
  82 For a filesystem that requires vnode lock to return any data, it does
  83 not make sense to implement
  84 .Nm
  85 (and set
  86 .Dv VIRF_PGREAD
  87 flag) since VFS arranges the call to
  88 .Xr VOP_READ 9
  89 as needed.
  90 .Pp
  91 The arguments are:
  92 .Bl -tag -width ioflag
  93 .It Fa vp
  94 The vnode of the file.
  95 .It Fa uio
  96 The location of the data to be read.
  97 .It Fa ioflag
  98 Various flags, see
  99 .Xr VOP_READ 9
 100 for the list.
 101 .It Fa cred
 102 The credentials of the caller.
 103 .El
 104 .Pp
 105 .Nm
 106 does not handle non-zero
 107 .Fa ioflag
 108 argument.
 109 .Sh LOCKS
 110 The file should be referenced on entry on entry and will still be
 111 referenced on exit.
 112 Rangelock covering the whole read range should be owned around the call.
 113 .Sh RETURN VALUES
 114 Zero is returned on success, when the whole request is satisfied, and no
 115 more data cannot be provided for it by any means.
 116 If more data can be returned, but
 117 .Nm
 118 was unable to provide it,
 119 .Er EJUSTRETURN
 120 must be returned.
 121 The
 122 .Dv uio
 123 records should be updated according to the partial operation done.
 124 .Pp
 125 Otherwise an error code is returned,
 126 same as from
 127 .Xr VOP_READ 9
 128 .Sh SEE ALSO
 129 .Xr uiomove 9 ,
 130 .Xr vnode 9 ,
 131 .Xr VOP_READ 9