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 September 12, 2014 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 reqpage" 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 reqpage 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 reqpage 82The index in the page array of the requested page; i.e., the one page which 83the implementation of this method must handle. 84.El 85.Pp 86The status of the 87.Fn VOP_PUTPAGES 88method is returned on a page-by-page basis in the array 89.Fa rtvals[] . 90The possible status values are as follows: 91.Bl -tag -width VM_PAGER_ERROR 92.It Dv VM_PAGER_OK 93The page was successfully written. 94The implementation must call 95.Xr vm_page_undirty 9 96to mark the page as clean. 97.It Dv VM_PAGER_PEND 98The page was scheduled to be written asynchronously. 99When the write completes, the completion callback should 100call 101.Xr vm_object_pip_wakeup 9 102and 103.Xr vm_page_sunbusy 9 104to clear the busy flag and awaken any other threads waiting for this page, 105in addition to calling 106.Xr vm_page_undirty 9 . 107.It Dv VM_PAGER_BAD 108The page was entirely beyond the end of the backing file. 109This condition should not be possible if the vnode's file system 110is correctly implemented. 111.It Dv VM_PAGER_ERROR 112The page could not be written because of an error on the underlying storage 113medium or protocol. 114.It Dv VM_PAGER_FAIL 115Treated identically to 116.Dv VM_PAGER_ERROR . 117.It Dv VM_PAGER_AGAIN 118The page was not handled by this request. 119.El 120.Pp 121The 122.Fn VOP_GETPAGES 123method is expected to release any pages in 124.Fa ma 125that it does not successfully handle, by calling 126.Xr vm_page_free 9 . 127When it succeeds, 128.Fn VOP_GETPAGES 129must set the valid bits appropriately. 130.Fn VOP_GETPAGES 131must keep 132.Fa reqpage 133busy. 134It must unbusy all other successfully handled pages and put them 135on appropriate page queue(s). 136For example, 137.Fn VOP_GETPAGES 138may either activate a page (if its wanted bit is set) 139or deactivate it (otherwise), and finally call 140.Xr vm_page_xunbusy 9 141to arouse any threads currently waiting for the page to be faulted in. 142.Sh RETURN VALUES 143If it successfully reads 144.Fa ma[reqpage] , 145.Fn VOP_GETPAGES 146returns 147.Dv VM_PAGER_OK ; 148otherwise, 149.Dv VM_PAGER_ERROR . 150By convention, the return value of 151.Fn VOP_PUTPAGES 152is 153.Fa rtvals[0] . 154.Sh SEE ALSO 155.Xr vm_object_pip_wakeup 9 , 156.Xr vm_page_free 9 , 157.Xr vm_page_sunbusy 9 , 158.Xr vm_page_undirty 9 , 159.Xr vm_page_xunbusy 9 , 160.Xr vnode 9 161.Sh AUTHORS 162This manual page was written by 163.An Doug Rabson 164and then substantially rewritten by 165.An Garrett Wollman . 166