VOP_GETPAGES(9)        FreeBSD Kernel Developer's Manual       VOP_GETPAGES(9)

NAME
     VOP_GETPAGES, VOP_PUTPAGES - read or write VM pages from a file

SYNOPSIS
     #include <sys/param.h>
     #include <sys/vnode.h>
     #include <vm/vm.h>

     int
     VOP_GETPAGES(struct vnode *vp, vm_page_t *ma, int count, int *rbehind,
         int *rahead);

     int
     VOP_PUTPAGES(struct vnode *vp, vm_page_t *ma, int bytecount, int flags,
         int *rtvals);

DESCRIPTION
     The 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, VOP_GETPAGES() is requested to read
     those pages as well, although it is not required to do so.  The
     VOP_PUTPAGES() method does the converse; that is to say, it writes out
     adjacent dirty pages of virtual memory.

     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.

     The arguments are:

     vp       The file to access.

     ma       Pointer to the first element of an array of pages representing a
              contiguous region of the file to be read or written.

     count    The length of the ma array.

     bytecount
              The number of bytes that should be written from the pages of the
              array.

     flags    A bitfield of flags affecting the function operation.  If
              VM_PAGER_PUT_SYNC is set, the write should be synchronous;
              control must not be returned to the caller until after the write
              is finished.  If VM_PAGER_PUT_INVAL is set, the pages are to be
              invalidated after being written.  If VM_PAGER_PUT_NOREUSE is
              set, the I/O performed should set the IO_NOREUSE flag, to
              indicate to the filesystem that pages should be marked for fast
              reuse if needed.  This could occur via a call to
              vm_page_deactivate_noreuse(9), which puts such pages onto the
              head of the inactive queue.  If VM_PAGER_CLUSTER_OK is set,
              writes may be delayed, so that related writes can be coalesced
              for efficiency, e.g., using the clustering mechanism of the
              buffer cache.

     rtvals   An array of VM system result codes indicating the status of each
              page written by VOP_PUTPAGES().

     rbehind  Optional pointer to integer specifying number of pages to be
              read behind, if possible.  If the filesystem supports that
              feature, number of actually read pages is reported back,
              otherwise zero is returned.

     rahead   Optional pointer to integer specifying number of pages to be
              read ahead, if possible.  If the filesystem supports that
              feature, number of actually read pages is reported back,
              otherwise zero is returned.

     The status of the VOP_PUTPAGES() method is returned on a page-by-page
     basis in the array rtvals[].  The possible status values are as follows:

     VM_PAGER_OK     The page was successfully written.  The implementation
                     must call vm_page_undirty(9) to mark the page as clean.

     VM_PAGER_PEND   The page was scheduled to be written asynchronously.
                     When the write completes, the completion callback should
                     call vm_object_pip_wakeup(9) and vm_page_sunbusy(9) to
                     clear the busy flag and awaken any other threads waiting
                     for this page, in addition to calling vm_page_undirty(9).

     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.

     VM_PAGER_ERROR  The page could not be written because of an error on the
                     underlying storage medium or protocol.

     VM_PAGER_FAIL   Treated identically to VM_PAGER_ERROR.

     VM_PAGER_AGAIN  The page was not handled by this request.

     The VOP_GETPAGES() method must populate and validate all requested pages
     in order to return success.  It is expected to release any pages in ma
     that it does not successfully handle, by calling vm_page_free(9).  When
     it succeeds, VOP_GETPAGES() must set the valid bits appropriately.  Upon
     entry to VOP_GETPAGES(), all pages in ma are busied exclusively.  Upon
     successful return, the pages must all be busied exclusively as well, but
     pages may be unbusied during processing.  The filesystem is responsible
     for activating paged-out pages, but this does not necessarily need to be
     done within VOP_GETPAGES() depending on the architecture of the
     particular filesystem.

RETURN VALUES
     If it successfully reads all pages in ma, VOP_GETPAGES() returns
     VM_PAGER_OK; otherwise, it returns VM_PAGER_ERROR.  By convention, the
     return value of VOP_PUTPAGES() is rtvals[0].

SEE ALSO
     vm_object_pip_wakeup(9), vm_page_free(9), vm_page_sunbusy(9),
     vm_page_undirty(9), vm_page_xunbusy(9), vnode(9)

AUTHORS
     This manual page was written by Doug Rabson and then substantially
     rewritten by
     Garrett Wollman.

FreeBSD 13.1-RELEASE-p6          June 29, 2019         FreeBSD 13.1-RELEASE-p6