1 files changed, 167 insertions, 0 deletions
diff --git a/share/man/man9/VOP_GETPAGES.9 b/share/man/man9/VOP_GETPAGES.9
new file mode 100644
index 0000000..7869d45
--- /dev/null
+++ b/share/man/man9/VOP_GETPAGES.9
@@ -0,0 +1,167 @@
+.\" -*- 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
+.Dt VOP_GETPAGES 9
+.Os
+.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 *ma" "int count" "int reqpage" "vm_ooffset_t offset"
+.Ft int
+.Fn VOP_PUTPAGES "struct vnode *vp" "vm_page_t *ma" "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 ma
+Pointer to the first element of an array of pages representing a
+contiguous region of the file to be read or written.
+.It Fa count
+The number of bytes that should be read into the pages of 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_sunbusy 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 ma
+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.
+.Fn VOP_GETPAGES
+must keep
+.Fa reqpage
+busy.
+It must unbusy all other successfully handled pages and put them
+on appropriate page queue(s).
+For example,
+.Fn VOP_GETPAGES
+may either activate a page (if its wanted bit is set)
+or deactivate it (otherwise), and finally call
+.Xr vm_page_xunbusy 9
+to arouse any threads currently waiting for the page to be faulted in.
+.Sh RETURN VALUES
+If it successfully reads
+.Fa ma[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_pagge_sunbusy 9 ,
+.Xr vm_page_undirty 9 ,
+.Xr vm_page_xunbusy 9 ,
+.Xr vnode 9
+.Sh AUTHORS
+This manual page was written by
+.An Doug Rabson
+and then substantially rewritten by
+.An Garrett Wollman .