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

NAME
     VOP_READ_PGCACHE - read a file, fast

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

     int
     VOP_READ_PGCACHE(struct vnode *vp, struct uio *uio, int ioflag,
         struct ucred *cred);

DESCRIPTION
     This entry point reads the contents of a file.  The intent is to provide
     the data from caches, which do not require expensive operations or any
     disk IO.  For instance, if filesystem uses normal VM page cache and
     maintains v_object lifetime, it can use vn_read_from_obj(9) helper to
     return data from the resident vp->v_object pages.

     The filesystem indicates support for the VOP_READ_PGCACHE on specific
     vnode by setting the VIRF_PGREAD flag in vp->v_irflag.

     The function does not need to satisfy the whole request; it also might
     choose to not provide any data.  In these cases, the uio must be advanced
     by the amount of read data, VOP_READ_PGCACHE should return EJUSTRETURN,
     and VFS would handle the rest of the read operation using the
     VOP_READ(9).

     The VFS layer does the same deadlock avoidance for accessing userspace
     pages from VOP_READ_PGCACHE as for VOP_READ(9).

     Vnode is not locked on the call entry and should not be locked on return.
     For a filesystem that requires vnode lock to return any data, it does not
     make sense to implement VOP_READ_PGCACHE (and set VIRF_PGREAD flag) since
     VFS arranges the call to VOP_READ(9) as needed.

     The arguments are:

     vp      The vnode of the file.

     uio     The location of the data to be read.

     ioflag  Various flags, see VOP_READ(9) for the list.

     cred    The credentials of the caller.

     VOP_READ_PGCACHE does not handle non-zero ioflag argument.

LOCKS
     The file should be referenced on entry on entry and will still be
     referenced on exit.  Rangelock covering the whole read range should be
     owned around the call.

RETURN VALUES
     Zero is returned on success, when the whole request is satisfied, and no
     more data cannot be provided for it by any means.  If more data can be
     returned, but VOP_READ_PGCACHE was unable to provide it, EJUSTRETURN must
     be returned.  The uio records should be updated according to the partial
     operation done.

     Otherwise an error code is returned, same as from VOP_READ(9)

SEE ALSO
     uiomove(9), vnode(9), VOP_READ(9)

FreeBSD 13.1-RELEASE-p6        February 28, 2021       FreeBSD 13.1-RELEASE-p6