Changeset View
Changeset View
Standalone 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 | |||||
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. | |||||
Done Inline ActionsWhere is the list of the accepted flags and its meaning? kib: Where is the list of the accepted flags and its meaning? | |||||
Done Inline ActionsFor this commit it has to be 0. khng: For this commit it has to be 0. | |||||
.It Fa cred | |||||
The credentials of the caller. | |||||
.Nm . | |||||
.El | |||||
Done Inline ActionsWhat is this? kib: What is this? | |||||
.Pp | |||||
The | |||||
.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 | |||||
Done Inline ActionsWhat 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. | |||||
Done Inline ActionsIt 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. | |||||
The file should be locked on entry and will still be locked on exit. | |||||
In case | |||||
Not Done Inline ActionsWhat it means 'file should be locked' ? kib: What it means 'file should be locked' ? | |||||
Done Inline Actionsvnode 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. | |||||
Done Inline ActionsThe 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. | |||||
.Dv SPACECTL_F_CANEXTEND | |||||
Done Inline ActionsI 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 ...
``` | |||||
is specified in | |||||
.Fa flags , | |||||
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. | |||||
Done Inline ActionsI 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. | |||||
.It Bq Er EPERM | |||||
An append-only flag is set on the file, but the caller is attempting to | |||||
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. |
It is better to use .Fo/.Fc for long prototypes