3 .\" Copyright (c) 1996 Doug Rabson
4 .\" Copyright 2003, Garrett A. Wollman
6 .\" All rights reserved.
8 .\" This program is free software.
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
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.
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.
38 .Nd read or write VM pages from a file
45 .Fa "struct vnode *vp"
53 .Fa "struct vnode *vp"
62 method is called to read in pages of virtual memory which are backed by
64 If other adjacent pages are backed by adjacent regions of the same file,
66 is requested to read those pages as well, although it is not required to
70 method does the converse; that is to say, it writes out adjacent dirty
71 pages of virtual memory.
73 On entry, the vnode lock is held but neither the page queue nor VM object
75 Both methods return in the same state on both success and error returns.
78 .Bl -tag -width rbehind
82 Pointer to the first element of an array of pages representing a
83 contiguous region of the file to be read or written.
89 The number of bytes that should be written from the pages of the array.
91 A bitfield of flags affecting the function operation.
94 is set, the write should be synchronous; control must not be returned
95 to the caller until after the write is finished.
97 .Dv VM_PAGER_PUT_INVAL
98 is set, the pages are to be invalidated after being written.
100 .Dv VM_PAGER_PUT_NOREUSE
101 is set, the I/O performed should set the IO_NOREUSE flag, to indicate
102 to the filesystem that pages should be marked for fast reuse if needed.
103 This could occur via a call to
104 .Xr vm_page_deactivate_noreuse 9 ,
105 which puts such pages onto the head of the inactive queue.
107 .Dv VM_PAGER_CLUSTER_OK
108 is set, writes may be delayed, so that related writes
109 can be coalesced for efficiency, e.g.,
110 using the clustering mechanism of the buffer cache.
112 An array of VM system result codes indicating the status of each
116 Optional pointer to integer specifying number of pages to be read behind, if
118 If the filesystem supports that feature, number of actually read pages is
119 reported back, otherwise zero is returned.
121 Optional pointer to integer specifying number of pages to be read ahead, if
123 If the filesystem supports that feature, number of actually read pages is
124 reported back, otherwise zero is returned.
129 method is returned on a page-by-page basis in the array
131 The possible status values are as follows:
132 .Bl -tag -width VM_PAGER_ERROR
134 The page was successfully written.
135 The implementation must call
136 .Xr vm_page_undirty 9
137 to mark the page as clean.
139 The page was scheduled to be written asynchronously.
140 When the write completes, the completion callback should
142 .Xr vm_object_pip_wakeup 9
144 .Xr vm_page_sunbusy 9
145 to clear the busy flag and awaken any other threads waiting for this page,
146 in addition to calling
147 .Xr vm_page_undirty 9 .
149 The page was entirely beyond the end of the backing file.
150 This condition should not be possible if the vnode's file system
151 is correctly implemented.
152 .It Dv VM_PAGER_ERROR
153 The page could not be written because of an error on the underlying storage
156 Treated identically to
158 .It Dv VM_PAGER_AGAIN
159 The page was not handled by this request.
164 method must populate and validate all requested pages in order to
166 It is expected to release any pages in
168 that it does not successfully handle, by calling
172 must set the valid bits appropriately.
177 are busied exclusively.
178 Upon successful return, the pages must all be busied exclusively
179 as well, but pages may be unbusied during processing.
180 The filesystem is responsible for activating paged-out pages, but this
181 does not necessarily need to be done within
183 depending on the architecture of the particular filesystem.
185 If it successfully reads all pages in
190 otherwise, it returns
192 By convention, the return value of
197 .Xr vm_object_pip_wakeup 9 ,
199 .Xr vm_page_sunbusy 9 ,
200 .Xr vm_page_undirty 9 ,
201 .Xr vm_page_xunbusy 9 ,
204 This manual page was written by
206 and then substantially rewritten by
207 .An Garrett Wollman .