1.\" Copyright (c) 2021 The FreeBSD Foundation 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.Dd February 28, 2021 29.Dt VOP_READ_PGCACHE 9 30.Os 31.Sh NAME 32.Nm VOP_READ_PGCACHE 33.Nd read a file, fast 34.Sh SYNOPSIS 35.In sys/param.h 36.In sys/vnode.h 37.In sys/uio.h 38.Ft int 39.Fo VOP_READ_PGCACHE 40.Fa "struct vnode *vp" 41.Fa "struct uio *uio" 42.Fa "int ioflag" 43.Fa "struct ucred *cred" 44.Fc 45.Sh DESCRIPTION 46This entry point reads the contents of a file. 47The intent is to provide the data from caches, which do not require 48expensive operations or any disk IO. 49For instance, if filesystem uses normal VM page cache and maintains 50.Dv v_object 51lifetime, it can use 52.Xr vn_read_from_obj 9 53helper to return data from the resident 54.Dv vp->v_object 55pages. 56.Pp 57The filesystem indicates support for the 58.Nm 59on specific vnode by setting the 60.Dv VIRF_PGREAD 61flag in 62.Dv vp->v_irflag . 63.Pp 64The function does not need to satisfy the whole request; it also might choose 65to not provide any data. 66In these cases, the 67.Fa uio 68must be advanced by the amount of read data, 69.Nm 70should return 71.Er EJUSTRETURN , 72and VFS would handle the rest of the read operation using the 73.Xr VOP_READ 9 . 74.Pp 75The VFS layer does the same deadlock avoidance for accessing userspace 76pages from 77.Nm 78as for 79.Xr VOP_READ 9 . 80.Pp 81Vnode is not locked on the call entry and should not be locked on return. 82For a filesystem that requires vnode lock to return any data, it does 83not make sense to implement 84.Nm 85(and set 86.Dv VIRF_PGREAD 87flag) since VFS arranges the call to 88.Xr VOP_READ 9 89as needed. 90.Pp 91The arguments are: 92.Bl -tag -width ioflag 93.It Fa vp 94The vnode of the file. 95.It Fa uio 96The location of the data to be read. 97.It Fa ioflag 98Various flags, see 99.Xr VOP_READ 9 100for the list. 101.It Fa cred 102The credentials of the caller. 103.El 104.Pp 105.Nm 106does not handle non-zero 107.Fa ioflag 108argument. 109.Sh LOCKS 110The file should be referenced on entry on entry and will still be 111referenced on exit. 112Rangelock covering the whole read range should be owned around the call. 113.Sh RETURN VALUES 114Zero is returned on success, when the whole request is satisfied, and no 115more data cannot be provided for it by any means. 116If more data can be returned, but 117.Nm 118was unable to provide it, 119.Er EJUSTRETURN 120must be returned. 121The 122.Dv uio 123records should be updated according to the partial operation done. 124.Pp 125Otherwise an error code is returned, 126same as from 127.Xr VOP_READ 9 128.Sh SEE ALSO 129.Xr uiomove 9 , 130.Xr vnode 9 , 131.Xr VOP_READ 9 132