Differential D29637 Diff 87003 share/man/man9/vnode_pager_setsize.9

Changeset View

Standalone View

share/man/man9/vnode_pager_setsize.9

	Show All 21 Lines
	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL			.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS			.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" 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			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.Dd April 6, 2021			.Dd April 8, 2021
	.Dt VNODE_PAGER_SETSIZE 9			.Dt VNODE_PAGER_SETSIZE 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm vnode_pager_setsize			.Nm vnode_pager_setsize
	.Nd "notify the VM system about updates in the file size"			.Nd "notify the VM system about updates in the file size"
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/param.h			.In sys/param.h
	.In vm/vm.h			.In vm/vm.h
	.In vm/vm_extern.h			.In vm/vm_extern.h
	.Ft void			.Ft void
	.Fn vnode_pager_setsize "struct vnode *vp" "vm_ooffset_t nsize"			.Fn vnode_pager_setsize "struct vnode *vp" "vm_ooffset_t nsize"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	.Nm			.Nm
	lets the VM system know about a change in size for a file.			lets the VM system know about a change in size for a file.
	Content beyond the new EOF specified by the			Content between the old EOF and the new EOF will be purged from the cache
				kibUnsubmitted Not Done Inline Actions 'Content purged from cache' is a vague slang, we usually formulate it in terms of 'pages removes from the object queue', and then you can clarify what happens with pages fully contained in the range, and what with the partial page. kib: 'Content purged from cache' is a vague slang, we usually formulate it in terms of 'pages…
	.Fa nsize			if the file size shrinks.
				kibUnsubmitted Done Inline Actions ... zeroed and marked invalid... kib: ... zeroed and marked invalid...
	argument will be purged from the cache.			In case the vnode
				.Fa vp
				does not have a VM object, the effect of calling this function is no-op.
				.Pp
				The new EOF is rounded up to the nearest page index as a boundary
				kibUnsubmitted Done Inline Actions This sentence is technically correct but sounds foreign even for me non-native. kib: This sentence is technically correct but sounds foreign even for me non-native.
				within which the page fault handler should handle.
				kibUnsubmitted Not Done Inline Actions I do not understand this paragraph at all. kib: I do not understand this paragraph at all.
				.Pp
				kibUnsubmitted Not Done Inline Actions What are you trying to say there? Page chunks at EOF are marked invalid, invalid cannot be dirty. kib: What are you trying to say there? Page chunks at EOF are marked invalid, invalid cannot be…
				kibUnsubmitted Not Done Inline Actions There are at least two object sizes for OBJT_VNODE, one is the size in pages, and another in bytes. I am not sure it makes much sense to try to articulate that assigning byte size to page size requires some arithmetic. kib: There are at least two object sizes for OBJT_VNODE, one is the size in pages, and another in…
	This function is useful for use within file system code to implement			This function is useful for use within file system code to implement
				kibUnsubmitted Not Done Inline Actions s/useful for use/must be used/ ... to implement truncation if filesystem allocated vm_object. kib: s/useful for use/must be used/ ... to implement truncation if filesystem allocated vm_object.
	truncation in			truncation in
	.Xr VOP_SETATTR 9 .			.Xr VOP_SETATTR 9 .
	.Sh IMPLEMENTATION NOTES			.Sh IMPLEMENTATION NOTES
				kibUnsubmitted Done Inline Actions vm object allocated kib: vm object allocated
				The function updates the object size of the vm object in
				.Fa vp
				with the new EOF specified by the
				.Fa nsize .
				kibUnsubmitted Not Done Inline Actions Arguably, this sentence is not an implementation note, but a good herald description of the function. kib: Arguably, this sentence is not an implementation note, but a good herald description of the…
	In case the new EOF specified by the			In case the new EOF specified by the
	.Fa nsize			.Fa nsize
	argument is not aligned to page boundaries,			argument is not aligned to page boundaries,
	partial-page area starting beyond the EOF will be zeroed.			partial-page area starting beyond the EOF will be zeroed.
				kibUnsubmitted Not Done Inline Actions will be zeroed if it exists resident. kib: will be zeroed if it exists resident.
	In partial-page area,			In partial-page area,
	for content occupying whole blocks within block			for content occupying whole blocks within block
	boundaries,			boundaries,
	the dirty bits for the corresponding blocks will be cleared.			the dirty bits for the corresponding blocks will be cleared.
	.Sh LOCKING			.Sh LOCKS
	Writer lock of the VM object of			The vnode should be exclusively locked on entry and will still be locked on exit.
	.Fa vp
	will be held within the function.
	.Sh SEE ALSO			.Sh SEE ALSO
	.Xr vnode 9			.Xr vnode 9
	.Sh HISTORY			.Sh HISTORY
	The			The
	.Nm			.Nm
	manual page first appeared in			manual page first appeared in
	.Fx 14 .			.Fx 14 .
	.Sh AUTHORS			.Sh AUTHORS
	This			This
	manual page was written by			manual page was written by
	.An Ka Ho Ng Aq Mt khng@FreeBSD.org .			.An Ka Ho Ng Aq Mt khng@FreeBSD.org .