diff options
Diffstat (limited to 'share/man/man9/VOP_GETPAGES.9')
| -rw-r--r-- | share/man/man9/VOP_GETPAGES.9 | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/share/man/man9/VOP_GETPAGES.9 b/share/man/man9/VOP_GETPAGES.9 new file mode 100644 index 000000000000..ffac609de133 --- /dev/null +++ b/share/man/man9/VOP_GETPAGES.9 @@ -0,0 +1,162 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" Copyright 2003, Garrett A. Wollman +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 27, 2003 +.Os +.Dt VOP_GETPAGES 9 +.Sh NAME +.Nm VOP_GETPAGES , +.Nm VOP_PUTPAGES +.Nd read or write VM pages from a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In vm/vm.h +.Ft int +.Fn VOP_GETPAGES "struct vnode *vp" "vm_page_t *m" "int count" "int reqpage" "vm_ooffset_t offset" +.Ft int +.Fn VOP_PUTPAGES "struct vnode *vp" "vm_page_t *m" "int count" "int sync" "int *rtvals" "vm_ooffset_t offset" +.Sh DESCRIPTION +The +.Fn VOP_GETPAGES +method is called to read in pages of virtual memory which are backed by +ordinary files. +If other adjacent pages are backed by adjacent regions of the same file, +.Fn VOP_GETPAGES +is requested to read those pages as well, although it is not required to +do so. +The +.Fn VOP_PUTPAGES +method does the converse; that is to say, it writes out adjacent dirty +pages of virtual memory. +.Pp +On entry, the vnode lock is held but neither the page queue nor VM object +locks are held. +Both methods return in the same state on both success and error returns. +.Pp +The arguments are: +.Bl -tag -width reqpage +.It Fa vp +The file to access. +.It Fa m +Pointer to the first element of an array of contiguous pages representing a +contiguous region of the file to be read or written. +.It Fa count +The number of pages in the array. +.It Fa sync +.Dv VM_PAGER_PUT_SYNC +if the write should be synchronous. +.It Fa rtvals +An array of VM system result codes indicating the status of each +page written by +.Fn VOP_PUTPAGES . +.It Fa reqpage +The index in the page array of the requested page; i.e., the one page which +the implementation of this method must handle. +.It Fa offset +Offset in the file at which the mapped pages begin. +.El +.Pp +The status of the +.Fn VOP_PUTPAGES +method is returned on a page-by-page basis in the array +.Fa rtvals[] . +The possible status values are as follows: +.Bl -tag -width VM_PAGER_ERROR +.It Dv VM_PAGER_OK +The page was successfully written. +The implementation must call +.Xr vm_page_undirty 9 +to mark the page as clean. +.It Dv VM_PAGER_PEND +The page was scheduled to be written asynchronously. +When the write completes, the completion callback should +call +.Xr vm_object_pip_wakeup 9 +and +.Xr vm_page_io_finish 9 +to clear the busy flag and awaken any other threads waiting for this page, +in addition to calling +.Xr vm_page_undirty 9 . +.It Dv VM_PAGER_BAD +The page was entirely beyond the end of the backing file. +This condition should not be possible if the vnode's file system +is correctly implemented. +.It Dv VM_PAGER_ERROR +The page could not be written because of an error on the underlying storage +medium or protocol. +.It Dv VM_PAGER_FAIL +Treated identically to +.Dv VM_PAGER_ERROR +.It Dv VM_PAGER_AGAIN +The page was not handled by this request. +.El +.Pp +The +.Fn VOP_GETPAGES +method is expected to release any pages in +.Fa m +that it does not successfully handle, by calling +.Xr vm_page_free 9 . +When it succeeds, +.Fn VOP_GETPAGES +must set the valid bits appropriately, clear the dirty bit +(using +.Xr vm_page_undirty 9 ) , +either activate the page (if its wanted bit is set) +or deactivate it (otherwise), and finally call +.Xr vm_page_wakeup 9 +to arouse any threads currently waiting for the page to be faulted in, +for each page read. +.Sh RETURN VALUES +If it successfully reads +.Fa m[reqpage] , +.Fn VOP_GETPAGES +returns +.Dv VM_PAGER_OK ; +otherwise, +.Dv VM_PAGER_ERROR . +By convention, the return value of +.Fn VOP_PUTPAGES +is +.Fa rtvals[0] . +.Sh SEE ALSO +.Xr vm_object_pip_wakeup 9 , +.Xr vm_page_free 9 , +.Xr vm_page_io_finish 9 , +.Xr vm_page_undirty 9 , +.Xr vm_page_wakeup 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson +and then substantially rewritten by +.An Garrett Wollman . |