Date: Thu, 8 Apr 2021 15:40:12 +0800 From: Ka Ho Ng <khng@FreeBSD.org> To: Konstantin Belousov <kostikbel@gmail.com> Cc: src-committers@freebsd.org, dev-commits-src-all@freebsd.org, dev-commits-src-main@freebsd.org Subject: Re: git: 86a52e262a6f - main - Document vnode_pager_setsize(9) Message-ID: <60a81778-d17a-2151-115a-ff7dad489771@FreeBSD.org> In-Reply-To: <YG4BDFkQkNtybU%2B0@kib.kiev.ua> References: <202104071113.137BD2Pj074018@gitrepo.freebsd.org> <YG4BDFkQkNtybU%2B0@kib.kiev.ua>
next in thread | previous in thread | raw e-mail | index | archive | help
On 4/8/21 2:59 am, Konstantin Belousov wrote: > On Wed, Apr 07, 2021 at 11:13:02AM +0000, Ka Ho Ng wrote: >> The branch main has been updated by khng: >> >> URL: https://cgit.FreeBSD.org/src/commit/?id=86a52e262a6faf75ee34eaa801f6d8ddaad20733 >> >> commit 86a52e262a6faf75ee34eaa801f6d8ddaad20733 >> Author: Ka Ho Ng <khng@FreeBSD.org> >> AuthorDate: 2021-04-07 11:00:31 +0000 >> Commit: Ka Ho Ng <khng@FreeBSD.org> >> CommitDate: 2021-04-07 11:11:26 +0000 >> >> Document vnode_pager_setsize(9) > I am sorry to say this, but the documentation is rather content-free. > > Main outcome of vnode_pager_setsize() is that it defines which offsets > from mapping of the file are handled by the fault handler, and which > results in SIGBUS. > > Clearing of the page cache is a secondary-level functionality, and more, > we allow to keep pages with indexes larger than the object size, on the > object queue. > >> >> MFC after: 3 days >> Sponsored by: The FreeBSD Foundation >> Reviewed by: bcr >> Approved by: philip (mentor) >> Differential Revision: https://reviews.freebsd.org/D29408 >> --- >> share/man/man9/Makefile | 1 + >> share/man/man9/vnode_pager_setsize.9 | 74 ++++++++++++++++++++++++++++++++++++ >> 2 files changed, 75 insertions(+) >> >> diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile >> index 52a5d373a417..efdd8b2f6e9c 100644 >> --- a/share/man/man9/Makefile >> +++ b/share/man/man9/Makefile >> @@ -401,6 +401,7 @@ MAN= accept_filter.9 \ >> vn_isdisk.9 \ >> vnet.9 \ >> vnode.9 \ >> + vnode_pager_setsize.9 \ >> VOP_ACCESS.9 \ >> VOP_ACLCHECK.9 \ >> VOP_ADVISE.9 \ >> diff --git a/share/man/man9/vnode_pager_setsize.9 b/share/man/man9/vnode_pager_setsize.9 >> new file mode 100644 >> index 000000000000..c59a01796f20 >> --- /dev/null >> +++ b/share/man/man9/vnode_pager_setsize.9 >> @@ -0,0 +1,74 @@ >> +.\" >> +.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD >> +.\" >> +.\" Copyright (c) 2021 The FreeBSD Foundation >> +.\" >> +.\" Portions of this software were developed by Ka Ho Ng >> +.\" under sponsorship from the FreeBSD Foundation. >> +.\" >> +.\" Redistribution and use in source and binary forms, with or without >> +.\" modification, are permitted provided that the following conditions >> +.\" are met: >> +.\" 1. Redistributions of source code must retain the above copyright >> +.\" notice, this list of conditions and the following disclaimer. >> +.\" 2. Redistributions in binary form must reproduce the above copyright >> +.\" notice, this list of conditions and the following disclaimer in the >> +.\" documentation and/or other materials provided with the distribution. >> +.\" >> +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND >> +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE >> +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE >> +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE >> +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL >> +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS >> +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) >> +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT >> +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY >> +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF >> +.\" SUCH DAMAGE. >> +.\" >> +.Dd April 6, 2021 >> +.Dt VNODE_PAGER_SETSIZE 9 >> +.Os >> +.Sh NAME >> +.Nm vnode_pager_setsize >> +.Nd "notify the VM system about updates in the file size" >> +.Sh SYNOPSIS >> +.In sys/param.h >> +.In vm/vm.h >> +.In vm/vm_extern.h >> +.Ft void >> +.Fn vnode_pager_setsize "struct vnode *vp" "vm_ooffset_t nsize" >> +.Sh DESCRIPTION >> +.Nm >> +lets the VM system know about a change in size for a file. >> +Content beyond the new EOF specified by the >> +.Fa nsize >> +argument will be purged from the cache. > This is not true. Only content between new EOF and old EOF is purged. > Removing everything past new EOF would break UFS, for instance. > >> +This function is useful for use within file system code to implement >> +truncation in >> +.Xr VOP_SETATTR 9 . >> +.Sh IMPLEMENTATION NOTES >> +In case the new EOF specified by the >> +.Fa nsize >> +argument is not aligned to page boundaries, >> +partial-page area starting beyond the EOF will be zeroed. >> +In partial-page area, >> +for content occupying whole blocks within block >> +boundaries, >> +the dirty bits for the corresponding blocks will be cleared. >> +.Sh LOCKING >> +Writer lock of the VM object of >> +.Fa vp >> +will be held within the function. > Object is locked internally on as needed basis, but why would this matter > for anybody? > > Again missed in the man page, but very important part of the interface > is that for correct and race-less use of the function, the vnode lock > must be held in exclusive mode. Otherwise truncation would interact > wrongly with page faults. > > Unfortunately not all filesystems lock the vnode, the last offender is > ZFS. For it, I had to add MNTK_VMSETSIZE_BUG to ignore the preconditions. > >> +.Sh SEE ALSO >> +.Xr vnode 9 >> +.Sh HISTORY >> +The >> +.Nm >> +manual page first appeared in >> +.Fx 14 . >> +.Sh AUTHORS >> +This >> +manual page was written by >> +.An Ka Ho Ng Aq Mt khng@FreeBSD.org . A new differential is posted as https://reviews.freebsd.org/D29637 to address them. Ka Ho
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?60a81778-d17a-2151-115a-ff7dad489771>