Differential D28347 Diff 84029 share/man/man9/VOP_DEALLOCATE.9

Changeset View

Standalone View

share/man/man9/VOP_DEALLOCATE.9

This file was added.

				.\"
				.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
				.\"
				.\" Copyright (c) 2021 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 Feb 10, 2021
				.Dt VOP_DEALLOCATE 9
				.Os
				.Sh NAME
				.Nm VOP_DEALLOCATE
				.Nd zero and/or deallocate storage from a file
				.Sh SYNOPSIS
				.In sys/param.h
				.In sys/vnode.h
				.Ft int
				.Fn VOP_DEALLOCATE "struct vnode vp" "off_t offset" "off_t len" "int flags" "struct ucred cred"
				.Sh DESCRIPTION
				kibUnsubmitted Done Inline Actions It is better to use .Fo/.Fc for long prototypes kib: It is better to use .Fo/.Fc for long prototypes
				This VOP call zeroes/deallocates storage for an offset range in a file.
				It is used to implement the
				.Xr fspacectl
				system call.
				.Pp
				Its arguments are:
				.Bl -tag -width offset
				.It Fa vp
				The vnode of the file.
				.It Fa offset
				The start of the range to allocate storage for in the file.
				.It Fa len
				The length of the range to allocate storage for in the file.
				.It Fa flags
				The parameter to control the behavior of this call.
				kibUnsubmitted Done Inline Actions Where is the list of the accepted flags and its meaning? kib: Where is the list of the accepted flags and its meaning?
				khngAuthorUnsubmitted Done Inline Actions For this commit it has to be 0. khng: For this commit it has to be 0.
				.Nm .
				.El
				.Pp
				The
				kibUnsubmitted Done Inline Actions What is this? kib: What is this?
				.Fa offset
				and
				.Fa len
				arguments are updated to reflect the portion of the range that
				still needs to be zeroed/deallocated on return.
				Partial result is considered a successful operation.
				The file's contents are not changed.
				.Sh LOCKS
				The file should be locked on entry and will still be locked on exit.
				In case
				kibUnsubmitted Done Inline Actions What does this sentence mean? I cannot understand it in context of the previous text. kib: What does this sentence mean? I cannot understand it in context of the previous text.
				khngAuthorUnsubmitted Done Inline Actions It was a leftover line when I was also trying to implement preallocation. Will clean this up. khng: It was a leftover line when I was also trying to implement preallocation. Will clean this up.
				.Dv SPACECTL_F_CANEXTEND
				is specified in
				kibUnsubmitted Not Done Inline Actions What it means 'file should be locked' ? kib: What it means 'file should be locked' ?
				khngAuthorUnsubmitted Done Inline Actions vnode lock has to be acquired (either shared or exclusively) before calling this function. khng: vnode lock has to be acquired (either shared or exclusively) before calling this function.
				khngAuthorUnsubmitted Done Inline Actions The line was actually the same as the one in LOCKS section in VOP_READ/VOP_WRITE/VOP_RDWR. khng: The line was actually the same as the one in LOCKS section in VOP_READ/VOP_WRITE/VOP_RDWR.
				.Fa flags ,
				kibUnsubmitted Done Inline Actions I think this should be The .Fa offset and .Fa len variables are updated ... kib: I think this should be ``` The .Fa offset and .Fa len variables are updated ... ```
				the file should be locked exclusively.
				.Sh RETURN VALUES
				Zero is returned if the call is successful, otherwise an appropriate
				error code is returned.
				.Sh ERRORS
				.Bl -tag -width Er
				.It Bq Er EINVAL
				Invalid
				.Fa offset , len
				or
				.Fa flags
				parameters are passed into this VOP call.
				.It Bq Er EFBIG
				An attempt was made to write a file that exceeds the process's file size
				limit or the maximum file size when SPACECTL_F_CANEXPAND is set in
				.Fa flags.
				.It Bq Er ENODEV
				The vnode type is not supported by this VOP call.
				.It Bq Er ENOSPC
				The file system is full.
				.It Bq Er EPERM
				An append-only flag is set on the file, but the caller is attempting to
				kibUnsubmitted Done Inline Actions I do not think that caller tries to write. At best, he tries to zero. kib: I do not think that caller tries to write. At best, he tries to zero.
				write before the current end of file.
				.El
				.Sh SEE ALSO
				.Xr vnode 9
				.Sh AUTHORS
				.Nm
				and this manual page were developed by
				.An Ka Ho Ng Aq Mt khng@FreeBSDFoundation.org
				under sponsorship from the FreeBSD Foundation.