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 27, 2003 33.Os 34.Dt VOP_GETPAGES 9 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 *m" "int count" "int reqpage" "vm_ooffset_t offset" 45.Ft int 46.Fn VOP_PUTPAGES "struct vnode *vp" "vm_page_t *m" "int count" "int sync" "int *rtvals" "vm_ooffset_t offset" 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 m 70Pointer to the first element of an array of contiguous pages representing a 71contiguous region of the file to be read or written. 72.It Fa count 73The number of pages in 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.It Fa offset 85Offset in the file at which the mapped pages begin. 86.El 87.Pp 88The status of the 89.Fn VOP_PUTPAGES 90method is returned on a page-by-page basis in the array 91.Fa rtvals[] . 92The possible status values are as follows: 93.Bl -tag -width VM_PAGER_ERROR 94.It Dv VM_PAGER_OK 95The page was successfully written. 96The implementation must call 97.Xr vm_page_undirty 9 98to mark the page as clean. 99.It Dv VM_PAGER_PEND 100The page was scheduled to be written asynchronously. 101When the write completes, the completion callback should 102call 103.Xr vm_object_pip_wakeup 9 104and 105.Xr vm_page_io_finish 9 106to clear the busy flag and awaken any other threads waiting for this page, 107in addition to calling 108.Xr vm_page_undirty 9 . 109.It Dv VM_PAGER_BAD 110The page was entirely beyond the end of the backing file. 111This condition should not be possible if the vnode's file system 112is correctly implemented. 113.It Dv VM_PAGER_ERROR 114The page could not be written because of an error on the underlying storage 115medium or protocol. 116.It Dv VM_PAGER_FAIL 117Treated identically to 118.Dv VM_PAGER_ERROR 119.It Dv VM_PAGER_AGAIN 120The page was not handled by this request. 121.El 122.Pp 123The 124.Fn VOP_GETPAGES 125method is expected to release any pages in 126.Fa m 127that it does not successfully handle, by calling 128.Xr vm_page_free 9 . 129When it succeeds, 130.Fn VOP_GETPAGES 131must set the valid bits appropriately, clear the dirty bit 132(using 133.Xr vm_page_undirty 9 ) , 134either activate the page (if its wanted bit is set) 135or deactivate it (otherwise), and finally call 136.Xr vm_page_wakeup 9 137to arouse any threads currently waiting for the page to be faulted in, 138for each page read. 139.Sh RETURN VALUES 140If it successfully reads 141.Fa m[reqpage] , 142.Fn VOP_GETPAGES 143returns 144.Dv VM_PAGER_OK ; 145otherwise, 146.Dv VM_PAGER_ERROR . 147By convention, the return value of 148.Fn VOP_PUTPAGES 149is 150.Fa rtvals[0] . 151.Sh SEE ALSO 152.Xr vm_object_pip_wakeup 9 , 153.Xr vm_page_free 9 , 154.Xr vm_page_io_finish 9 , 155.Xr vm_page_undirty 9 , 156.Xr vm_page_wakeup 9 , 157.Xr vnode 9 158.Sh AUTHORS 159This manual page was written by 160.An Doug Rabson 161and then substantially rewritten by 162.An Garrett Wollman . 163