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