git: 75f7db7c11fe - stable/12 - vnode_pager_setsize.9: Some clarifications on the manpage

[Ka Ho Ng]

The branch stable/12 has been updated by khng:

URL: https://cgit.FreeBSD.org/src/commit/?id=75f7db7c11fe27ab4d5f41c28973aaf1bab912b7

commit 75f7db7c11fe27ab4d5f41c28973aaf1bab912b7
Author:     Ka Ho Ng <khng at FreeBSD.org>
AuthorDate: 2021-04-11 06:45:37 +0000
Commit:     Ka Ho Ng <khng at FreeBSD.org>
CommitDate: 2021-09-03 18:46:40 +0000

    vnode_pager_setsize.9: Some clarifications on the manpage
    
    A number of changes:
    - Clarifies the locking rules when calling the routine.
    - Correct the description regarding the content range to be purged.
    - Document the effects on page fault handler.
    
    MFC with:       86a52e262a6f
    Sponsored by:   The FreeBSD Foundation
    Reviewed by:    bcr, kib
    Approved by:    philip (mentor)
    Differential Revision:  https://reviews.freebsd.org/D29637
    
    (cherry picked from commit b77f5f5553e8ac7868b4b234a36bda3cf2db0907)
---
 share/man/man9/vnode_pager_setsize.9 | 41 ++++++++++++++++++++----------------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/share/man/man9/vnode_pager_setsize.9 b/share/man/man9/vnode_pager_setsize.9
index c59a01796f20..0dc3b2057930 100644
--- a/share/man/man9/vnode_pager_setsize.9
+++ b/share/man/man9/vnode_pager_setsize.9
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd April 6, 2021
+.Dd April 8, 2021
 .Dt VNODE_PAGER_SETSIZE 9
 .Os
 .Sh NAME
@@ -41,26 +41,31 @@
 .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 function is useful for use within file system code to implement
-truncation in
-.Xr VOP_SETATTR 9 .
-.Sh IMPLEMENTATION NOTES
+lets the VM system know about a change in size for a file,
+and updates the object size and vnode pager size of the vm object in
+.Fa vp
+with
+.Fa nsize .
+Page faults on the object mapping with offset beyond the new object
+size results in
+.Va SIGBUS .
+.Pp
+Pages between the old EOF and the new EOF are removed from the object queue
+if the file size shrinks.
 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
+argument is not aligned to page boundary,
+partial-page area starting beyond the EOF is zeroed and marked invalid.
+if the page exists resident.
+.Pp
+In case the vnode
 .Fa vp
-will be held within the function.
+does not have a VM object allocated, the effect of calling this function is no-op.
+.Pp
+This function must be used within file system code to implement truncation
+if the file system allocates vm objects for vnodes.
+.Sh LOCKS
+The vnode should be exclusively locked on entry and will still be locked on exit.
 .Sh SEE ALSO
 .Xr vnode 9
 .Sh HISTORY