Differential D28347 Diff 87509 share/man/man9/vn_deallocate.9

Changeset View

Standalone View

share/man/man9/vn_deallocate.9

This file was copied from share/man/man9/vnode_pager_purge_range.9.

	Show All 18 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 January 26, 2021			.Dd April 16, 2021
	.Dt VNODE_PAGER_PURGE_RANGE 9			.Dt VN_DEALLOCATE 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm vnode_pager_purge_range			.Nm vn_deallocate
	.Nd "invalidate the content of the given range in bytes from cache"			.Nd zero and/or deallocate storage from a file
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/param.h			.In sys/param.h
	.In vm/vm.h			.In sys/vnode.h
	.In vm/vm_extern.h			.Ft int
	.Ft void			.Fo vn_deallocate
	.Fn vnode_pager_purge_range "struct vnode *vp" "vm_ooffset_t startoff" "vm_ooffset_t endoff"			.Fa "struct vnode *vp"
				.Fa "off_t offset"
				.Fa "off_t len"
				.Fa "int flags"
				bcrUnsubmitted Done Inline Actions Not sure about this one: s/deallocate/deallocates/ bcr: Not sure about this one: s/deallocate/deallocates/
				.Fa "int ioflg"
				.Fa "struct ucred *active_cred"
				.Fa "struct ucred *file_cred"
				.Fc
	.Sh DESCRIPTION			.Sh DESCRIPTION
	.Nm
	invalidates content of the cache covered by the given range from the
	specified vnode
	.Fa vp .
	The range to be purged is
	.Eo [
	.Fa startoff , endoff
	.Ec ) .
	Affected pages within the specified range will be tossed away.
	.Sh IMPLEMENTATION NOTES
	Within the specified range,
	in case
	.Fa startoff
	or
	.Fa endoff
	is not aligned to page boundaries,
	partial-page area 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.
	.Sh SEE ALSO
	.Xr vnode 9
	.Sh HISTORY
	The			The
	.Nm			.Fn vn_deallocate
	manual page first appeared in			function zeros and/or deallocates backing storage space from a file.
	.Fx 14 .			This function only works on vnodes with
				.Dv VREG
				type.
				.Pp
				bcrUnsubmitted Not Done Inline Actions Needs a line break here after the sentence stop. bcr: Needs a line break here after the sentence stop.
				The arguments are:
				.Bl -tag -width active_cred
				.It Fa vp
				The vnode of the file.
				.It Fa offset
				The starting offset of the operation range.
				.It Fa len
				The length of the operation range.
				This must be greater than 0.
				.It Fa flags
				The control flags of the operation.
				This should be set to 0 for now.
				.It Fa ioflg
				The control flags of vnode locking.
				.It Fa active_cred
				The user credentials of the calling thread.
				.It Fa file_cred
				The credentials installed on the file description pointing to the vnode or NOCRED.
				.El
				kibUnsubmitted Not Done Inline Actions What is this? kib: What is this?
				khngAuthorUnsubmitted Done Inline Actions Leftover from implementing posix_fallocate. Will clean this up. khng: Leftover from implementing posix_fallocate. Will clean this up.
				.Pp
				The
				.Fn ioflg
				argument may be one or more of the following flags:
				.Bl -tag -width IO_RANGELOCKED
				.It Dv IO_NODELOCKED
				The vnode was locked on entry to this function.
				.It Dv IO_RANGELOCKED
				Rangelock was owned around the call.
				.El
				kibUnsubmitted Not Done Inline Actions What it means 'granted'? kib: What it means 'granted'?
				khngAuthorUnsubmitted Done Inline Actions 'acquired' khng: 'acquired'
				.Sh RETURN VALUES
				Upon successful completion, the value 0 is returned; otherwise the
				appropriate error is returned.
				.Sh SEE ALSO
				.Xr vnode 9 ,
				.Xr VOP_DEALLOCATE 9
	.Sh AUTHORS			.Sh AUTHORS
	This			.Nm
	manual page was written by			and this manual page were developed by
	.An Ka Ho Ng Aq Mt khng@freebsdfoundation.org .			.An Ka Ho Ng Aq Mt khng@FreeBSDFoundation.org
				under sponsorship from the FreeBSD Foundation.