share/man/man9/VOP_GETPAGES.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 1996 Doug Rabson
   4 .\" Copyright 2003, Garrett A. Wollman
   5 .\"
   6 .\" All rights reserved.
   7 .\"
   8 .\" This program is free software.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  22 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd June 29, 2019
  33 .Dt VOP_GETPAGES 9
  34 .Os
  35 .Sh NAME
  36 .Nm VOP_GETPAGES ,
  37 .Nm VOP_PUTPAGES
  38 .Nd read or write VM pages from a file
  39 .Sh SYNOPSIS
  40 .In sys/param.h
  41 .In sys/vnode.h
  42 .In vm/vm.h
  43 .Ft int
  44 .Fo VOP_GETPAGES
  45 .Fa "struct vnode *vp"
  46 .Fa "vm_page_t *ma"
  47 .Fa "int count"
  48 .Fa "int *rbehind"
  49 .Fa "int *rahead"
  50 .Fc
  51 .Ft int
  52 .Fo VOP_PUTPAGES
  53 .Fa "struct vnode *vp"
  54 .Fa "vm_page_t *ma"
  55 .Fa "int bytecount"
  56 .Fa "int flags"
  57 .Fa "int *rtvals"
  58 .Fc
  59 .Sh DESCRIPTION
  60 The
  61 .Fn VOP_GETPAGES
  62 method is called to read in pages of virtual memory which are backed by
  63 ordinary files.
  64 If other adjacent pages are backed by adjacent regions of the same file,
  65 .Fn VOP_GETPAGES
  66 is requested to read those pages as well, although it is not required to
  67 do so.
  68 The
  69 .Fn VOP_PUTPAGES
  70 method does the converse; that is to say, it writes out adjacent dirty
  71 pages of virtual memory.
  72 .Pp
  73 On entry, the vnode lock is held but neither the page queue nor VM object
  74 locks are held.
  75 Both methods return in the same state on both success and error returns.
  76 .Pp
  77 The arguments are:
  78 .Bl -tag -width rbehind
  79 .It Fa vp
  80 The file to access.
  81 .It Fa ma
  82 Pointer to the first element of an array of pages representing a
  83 contiguous region of the file to be read or written.
  84 .It Fa count
  85 The length of the
  86 .Fa ma
  87 array.
  88 .It Fa bytecount
  89 The number of bytes that should be written from the pages of the array.
  90 .It Fa flags
  91 A bitfield of flags affecting the function operation.
  92 If
  93 .Dv VM_PAGER_PUT_SYNC
  94 is set, the write should be synchronous; control must not be returned
  95 to the caller until after the write is finished.
  96 If
  97 .Dv VM_PAGER_PUT_INVAL
  98 is set, the pages are to be invalidated after being written.
  99 If
 100 .Dv VM_PAGER_PUT_NOREUSE
 101 is set, the I/O performed should set the IO_NOREUSE flag, to indicate
 102 to the filesystem that pages should be marked for fast reuse if needed.
 103 This could occur via a call to
 104 .Xr vm_page_deactivate_noreuse 9 ,
 105 which puts such pages onto the head of the inactive queue.
 106 If
 107 .Dv VM_PAGER_CLUSTER_OK
 108 is set, writes may be delayed, so that related writes
 109 can be coalesced for efficiency, e.g.,
 110 using the clustering mechanism of the buffer cache.
 111 .It Fa rtvals
 112 An array of VM system result codes indicating the status of each
 113 page written by
 114 .Fn VOP_PUTPAGES .
 115 .It Fa rbehind
 116 Optional pointer to integer specifying number of pages to be read behind, if
 117 possible.
 118 If the filesystem supports that feature, number of actually read pages is
 119 reported back, otherwise zero is returned.
 120 .It Fa rahead
 121 Optional pointer to integer specifying number of pages to be read ahead, if
 122 possible.
 123 If the filesystem supports that feature, number of actually read pages is
 124 reported back, otherwise zero is returned.
 125 .El
 126 .Pp
 127 The status of the
 128 .Fn VOP_PUTPAGES
 129 method is returned on a page-by-page basis in the array
 130 .Fa rtvals[] .
 131 The possible status values are as follows:
 132 .Bl -tag -width VM_PAGER_ERROR
 133 .It Dv VM_PAGER_OK
 134 The page was successfully written.
 135 The implementation must call
 136 .Xr vm_page_undirty 9
 137 to mark the page as clean.
 138 .It Dv VM_PAGER_PEND
 139 The page was scheduled to be written asynchronously.
 140 When the write completes, the completion callback should
 141 call
 142 .Xr vm_object_pip_wakeup 9
 143 and
 144 .Xr vm_page_sunbusy 9
 145 to clear the busy flag and awaken any other threads waiting for this page,
 146 in addition to calling
 147 .Xr vm_page_undirty 9 .
 148 .It Dv VM_PAGER_BAD
 149 The page was entirely beyond the end of the backing file.
 150 This condition should not be possible if the vnode's file system
 151 is correctly implemented.
 152 .It Dv VM_PAGER_ERROR
 153 The page could not be written because of an error on the underlying storage
 154 medium or protocol.
 155 .It Dv VM_PAGER_FAIL
 156 Treated identically to
 157 .Dv VM_PAGER_ERROR .
 158 .It Dv VM_PAGER_AGAIN
 159 The page was not handled by this request.
 160 .El
 161 .Pp
 162 The
 163 .Fn VOP_GETPAGES
 164 method must populate and validate all requested pages in order to
 165 return success.
 166 It is expected to release any pages in
 167 .Fa ma
 168 that it does not successfully handle, by calling
 169 .Xr vm_page_free 9 .
 170 When it succeeds,
 171 .Fn VOP_GETPAGES
 172 must set the valid bits appropriately.
 173 Upon entry to
 174 .Fn VOP_GETPAGES ,
 175 all pages in
 176 .Fa ma
 177 are busied exclusively.
 178 Upon successful return, the pages must all be busied exclusively
 179 as well, but pages may be unbusied during processing.
 180 The filesystem is responsible for activating paged-out pages, but this
 181 does not necessarily need to be done within
 182 .Fn VOP_GETPAGES
 183 depending on the architecture of the particular filesystem.
 184 .Sh RETURN VALUES
 185 If it successfully reads all pages in
 186 .Fa ma ,
 187 .Fn VOP_GETPAGES
 188 returns
 189 .Dv VM_PAGER_OK ;
 190 otherwise, it returns
 191 .Dv VM_PAGER_ERROR .
 192 By convention, the return value of
 193 .Fn VOP_PUTPAGES
 194 is
 195 .Fa rtvals[0] .
 196 .Sh SEE ALSO
 197 .Xr vm_object_pip_wakeup 9 ,
 198 .Xr vm_page_free 9 ,
 199 .Xr vm_page_sunbusy 9 ,
 200 .Xr vm_page_undirty 9 ,
 201 .Xr vm_page_xunbusy 9 ,
 202 .Xr vnode 9
 203 .Sh AUTHORS
 204 This manual page was written by
 205 .An Doug Rabson
 206 and then substantially rewritten by
 207 .An Garrett Wollman .