1.\" Copyright (c) 2021 The FreeBSD Foundation, Inc. 2.\" 3.\" This documentation was written by 4.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship 5.\" from the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd February 28, 2021 31.Dt VOP_READ_PGCACHE 9 32.Os 33.Sh NAME 34.Nm VOP_READ_PGCACHE 35.Nd read a file, fast 36.Sh SYNOPSIS 37.In sys/param.h 38.In sys/vnode.h 39.In sys/uio.h 40.Ft int 41.Fo VOP_READ_PGCACHE 42.Fa "struct vnode *vp" 43.Fa "struct uio *uio" 44.Fa "int ioflag" 45.Fa "struct ucred *cred" 46.Fc 47.Sh DESCRIPTION 48This entry point reads the contents of a file. 49The intent is to provide the data from caches, which do not require 50expensive operations or any disk IO. 51For instance, if filesystem uses normal VM page cache and maintains 52.Dv v_object 53lifetime, it can use 54.Xr vn_read_from_obj 9 55helper to return data from the resident 56.Dv vp->v_object 57pages. 58.Pp 59The filesystem indicates support for the 60.Nm 61on specific vnode by setting the 62.Dv VIRF_PGREAD 63flag in 64.Dv vp->v_irflag . 65.Pp 66The function does not need to satisfy the whole request; it also might choose 67to not provide any data. 68In these cases, the 69.Fa uio 70must be advanced by the amount of read data, 71.Nm 72should return 73.Er EJUSTRETURN , 74and VFS would handle the rest of the read operation using the 75.Xr VOP_READ 9 . 76.Pp 77The VFS layer does the same deadlock avoidance for accessing userspace 78pages from 79.Nm 80as for 81.Xr VOP_READ 9 . 82.Pp 83Vnode is not locked on the call entry and should not be locked on return. 84For a filesystem that requires vnode lock to return any data, it does 85not make sense to implement 86.Nm 87(and set 88.Dv VIRF_PGREAD 89flag) since VFS arranges the call to 90.Xr VOP_READ 9 91as needed. 92.Pp 93The arguments are: 94.Bl -tag -width ioflag 95.It Fa vp 96The vnode of the file. 97.It Fa uio 98The location of the data to be read. 99.It Fa ioflag 100Various flags, see 101.Xr VOP_READ 9 102for the list. 103.It Fa cred 104The credentials of the caller. 105.El 106.Pp 107.Nm 108does not handle non-zero 109.Fa ioflag 110argument. 111.Sh LOCKS 112The file should be referenced on entry on entry and will still be 113referenced on exit. 114Rangelock covering the whole read range should be owned around the call. 115.Sh RETURN VALUES 116Zero is returned on success, when the whole request is satisfied, and no 117more data cannot be provided for it by any means. 118If more data can be returned, but 119.Nm 120was unable to provide it, 121.Er EJUSTRETURN 122must be returned. 123The 124.Dv uio 125records should be updated according to the partial operation done. 126.Pp 127Otherwise an error code is returned, 128same as from 129.Xr VOP_READ 9 130.Sh SEE ALSO 131.Xr uiomove 9 , 132.Xr vnode 9 , 133.Xr VOP_READ 9 134