git: 86a52e262a6f - main - Document vnode_pager_setsize(9)

Thu Apr 8 07:40:18 UTC 2021

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 at FreeBSD.org>
>> AuthorDate: 2021-04-07 11:00:31 +0000
>> Commit:     Ka Ho Ng <khng at 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 at FreeBSD.org .
A new differential is posted as https://reviews.freebsd.org/D29637 to 
address them.

Ka Ho