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 December 16, 2015 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.Fn VOP_GETPAGES "struct vnode *vp" "vm_page_t *ma" "int count" "int *rbehind" "int *rahead" 45.Ft int 46.Fn VOP_PUTPAGES "struct vnode *vp" "vm_page_t *ma" "int count" "int sync" "int *rtvals" 47.Sh DESCRIPTION 48The 49.Fn VOP_GETPAGES 50method is called to read in pages of virtual memory which are backed by 51ordinary files. 52If other adjacent pages are backed by adjacent regions of the same file, 53.Fn VOP_GETPAGES 54is requested to read those pages as well, although it is not required to 55do so. 56The 57.Fn VOP_PUTPAGES 58method does the converse; that is to say, it writes out adjacent dirty 59pages of virtual memory. 60.Pp 61On entry, the vnode lock is held but neither the page queue nor VM object 62locks are held. 63Both methods return in the same state on both success and error returns. 64.Pp 65The arguments are: 66.Bl -tag -width rbehind 67.It Fa vp 68The file to access. 69.It Fa ma 70Pointer to the first element of an array of pages representing a 71contiguous region of the file to be read or written. 72.It Fa count 73The number of bytes that should be read into the pages of the array. 74.It Fa sync 75.Dv VM_PAGER_PUT_SYNC 76if the write should be synchronous. 77.It Fa rtvals 78An array of VM system result codes indicating the status of each 79page written by 80.Fn VOP_PUTPAGES . 81.It Fa rbehind 82Optional pointer to integer specifying number of pages to be read behind, if 83possible. 84If the filesystem supports that feature, number of actually read pages is 85reported back, otherwise zero is returned. 86.It Fa rahead 87Optional pointer to integer specifying number of pages to be read ahead, if 88possible. 89If the filesystem supports that feature, number of actually read pages is 90reported back, otherwise zero is returned. 91.El 92.Pp 93The status of the 94.Fn VOP_PUTPAGES 95method is returned on a page-by-page basis in the array 96.Fa rtvals[] . 97The possible status values are as follows: 98.Bl -tag -width VM_PAGER_ERROR 99.It Dv VM_PAGER_OK 100The page was successfully written. 101The implementation must call 102.Xr vm_page_undirty 9 103to mark the page as clean. 104.It Dv VM_PAGER_PEND 105The page was scheduled to be written asynchronously. 106When the write completes, the completion callback should 107call 108.Xr vm_object_pip_wakeup 9 109and 110.Xr vm_page_sunbusy 9 111to clear the busy flag and awaken any other threads waiting for this page, 112in addition to calling 113.Xr vm_page_undirty 9 . 114.It Dv VM_PAGER_BAD 115The page was entirely beyond the end of the backing file. 116This condition should not be possible if the vnode's file system 117is correctly implemented. 118.It Dv VM_PAGER_ERROR 119The page could not be written because of an error on the underlying storage 120medium or protocol. 121.It Dv VM_PAGER_FAIL 122Treated identically to 123.Dv VM_PAGER_ERROR . 124.It Dv VM_PAGER_AGAIN 125The page was not handled by this request. 126.El 127.Pp 128The 129.Fn VOP_GETPAGES 130method is expected to release any pages in 131.Fa ma 132that it does not successfully handle, by calling 133.Xr vm_page_free 9 . 134When it succeeds, 135.Fn VOP_GETPAGES 136must set the valid bits appropriately. 137.Fn VOP_GETPAGES 138must keep 139.Fa reqpage 140busy. 141It must unbusy all other successfully handled pages and put them 142on appropriate page queue(s). 143For example, 144.Fn VOP_GETPAGES 145may either activate a page (if its wanted bit is set) 146or deactivate it (otherwise), and finally call 147.Xr vm_page_xunbusy 9 148to arouse any threads currently waiting for the page to be faulted in. 149.Sh RETURN VALUES 150If it successfully reads 151.Fa ma[reqpage] , 152.Fn VOP_GETPAGES 153returns 154.Dv VM_PAGER_OK ; 155otherwise, 156.Dv VM_PAGER_ERROR . 157By convention, the return value of 158.Fn VOP_PUTPAGES 159is 160.Fa rtvals[0] . 161.Sh SEE ALSO 162.Xr vm_object_pip_wakeup 9 , 163.Xr vm_page_free 9 , 164.Xr vm_page_sunbusy 9 , 165.Xr vm_page_undirty 9 , 166.Xr vm_page_xunbusy 9 , 167.Xr vnode 9 168.Sh AUTHORS 169This manual page was written by 170.An Doug Rabson 171and then substantially rewritten by 172.An Garrett Wollman . 173