Differential D29637 Diff 87236 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,
				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…
				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…
				kibUnsubmitted Done Inline Actions ... zeroed and marked invalid... kib: ... zeroed and marked invalid...
				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.
	Content beyond the new EOF specified by the			and updates the object size and vnode pager size of the vm object in
	.Fa nsize			.Fa vp
	argument will be purged from the cache.			with
	This function is useful for use within file system code to implement			.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…
	truncation in			Page faults on the object mapping with offset beyond the new object
				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.
	.Xr VOP_SETATTR 9 .			size results in
				kibUnsubmitted Not Done Inline Actions I do not understand this paragraph at all. kib: I do not understand this paragraph at all.
	.Sh IMPLEMENTATION NOTES			.Va SIGBUS .
				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…
				.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			In case the new EOF specified by the
				kibUnsubmitted Done Inline Actions vm object allocated kib: vm object allocated
	.Fa nsize			.Fa nsize
	argument is not aligned to page boundaries,			argument is not aligned to page boundary,
				kibUnsubmitted Not Done Inline Actions will be zeroed if it exists resident. kib: will be zeroed if it exists resident.
	partial-page area starting beyond the EOF will be zeroed.			partial-page area starting beyond the EOF is zeroed and marked invalid.
	In partial-page area,			if the page exists resident.
	for content occupying whole blocks within block			.Pp
	boundaries,			In case the vnode
	the dirty bits for the corresponding blocks will be cleared.
	.Sh LOCKING
	Writer lock of the VM object of
	.Fa vp			.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			.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 .