Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/VOP_DEALLOCATE.9
- This file was copied from share/man/man9/VOP_ALLOCATE.9.
.\" -*- nroff -*- | |||||
.\" | .\" | ||||
.\" Copyright (c) 2013 Hudson River Trading LLC | .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD | ||||
.\" Written by: John H. Baldwin <jhb@FreeBSD.org> | |||||
.\" All rights reserved. | |||||
.\" | .\" | ||||
.\" Copyright (c) 2021 The FreeBSD Foundation | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | ||||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||||
.\" are met: | .\" are met: | ||||
.\" 1. Redistributions of source code must retain the above copyright | .\" 1. Redistributions of source code must retain the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer. | .\" notice, this list of conditions and the following disclaimer. | ||||
.\" 2. Redistributions in binary form must reproduce the above copyright | .\" 2. Redistributions in binary form must reproduce the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer in the | .\" notice, this list of conditions and the following disclaimer in the | ||||
.\" documentation and/or other materials provided with the distribution. | .\" documentation and/or other materials provided with the distribution. | ||||
.\" | .\" | ||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | ||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | ||||
.\" 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. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .Dd Feb 10, 2021 | ||||
.\" | .Dt VOP_DEALLOCATE 9 | ||||
.Dd October 3, 2013 | |||||
.Dt VOP_ALLOCATE 9 | |||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm VOP_ALLOCATE | .Nm VOP_DEALLOCATE | ||||
.Nd allocate storage for a file | .Nd zero and/or deallocate storage from a file | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In sys/param.h | .In sys/param.h | ||||
.In sys/vnode.h | .In sys/vnode.h | ||||
.Ft int | .Ft int | ||||
.Fn VOP_ALLOCATE "struct vnode *vp" "off_t *offset" "off_t *len" | .Fn VOP_DEALLOCATE "struct vnode *vp" "off_t *offset" "off_t *len" "int flags" "struct ucred *cred" | ||||
kib: It is better to use .Fo/.Fc for long prototypes | |||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
This call allocates storage for a range of offsets in a file. | This VOP call zeroes/deallocates storage for an offset range in a file. | ||||
It is used to implement the | It is used to implement the | ||||
.Xr posix_fallocate | .Xr fspacectl | ||||
system call. | system call. | ||||
.Pp | .Pp | ||||
Its arguments are: | Its arguments are: | ||||
.Bl -tag -width offset | .Bl -tag -width offset | ||||
.It Fa vp | .It Fa vp | ||||
The vnode of the file. | The vnode of the file. | ||||
.It Fa offset | .It Fa offset | ||||
The start of the range to allocate storage for in the file. | The start of the range to allocate storage for in the file. | ||||
.It Fa len | .It Fa len | ||||
The length of the range to allocate storage for in the file. | The length of the range to allocate storage for in the file. | ||||
.It Fa flags | |||||
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. | |||||
The parameter to control the behavior of this call. | |||||
.It Fa cred | |||||
The credentials of the caller. | |||||
.Nm . | |||||
Done Inline ActionsWhat is this? kib: What is this? | |||||
.El | .El | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fa offset | .Fa offset | ||||
and | and | ||||
.Fa len | .Fa len | ||||
arguments are updated to reflect the portion of the range that | arguments are updated to reflect the portion of the range that | ||||
still needs to be allocated on return. | still needs to be zeroed/deallocated on return. | ||||
A partial allocation is considered a successful operation. | Partial result is considered a successful operation. | ||||
The file's contents are not changed. | The file's contents are not changed. | ||||
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. | |||||
.Sh LOCKS | .Sh LOCKS | ||||
The file should be exclusively locked on entry and will still be locked on exit. | The file should be locked on entry and will still be locked on exit. | ||||
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. | |||||
In case | |||||
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 ...
``` | |||||
.Dv SPACECTL_F_CANEXTEND | |||||
is specified in | |||||
.Fa flags , | |||||
the file should be locked exclusively. | |||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
Zero is returned if the call is successful, otherwise an appropriate | Zero is returned if the call is successful, otherwise an appropriate | ||||
error code is returned. | error code is returned. | ||||
.Sh ERRORS | .Sh ERRORS | ||||
.Bl -tag -width Er | .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 | .It Bq Er EFBIG | ||||
An attempt was made to write a file that exceeds the process's file size | An attempt was made to write a file that exceeds the process's file size | ||||
limit or the maximum 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 | .It Bq Er ENOSPC | ||||
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. | |||||
The file system is full. | The file system is full. | ||||
.It Bq Er EPERM | .It Bq Er EPERM | ||||
An append-only flag is set on the file, but the caller is attempting to | An append-only flag is set on the file, but the caller is attempting to | ||||
write before the current end of file. | write before the current end of file. | ||||
.El | .El | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr vnode 9 , | .Xr vnode 9 | ||||
.Xr VOP_READ 9 , | .Sh AUTHORS | ||||
.Xr VOP_WRITE 9 | .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