1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2021 The FreeBSD Foundation 5.\" 6.\" This manual page was written by Ka Ho Ng under sponsorship from 7.\" the FreeBSD Foundation. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd August 25, 2021 31.Dt VN_DEALLOCATE 9 32.Os 33.Sh NAME 34.Nm vn_deallocate 35.Nd zero and/or deallocate storage from a file 36.Sh SYNOPSIS 37.In sys/param.h 38.In sys/vnode.h 39.Ft int 40.Fo vn_deallocate 41.Fa "struct vnode *vp" 42.Fa "off_t *offset" 43.Fa "off_t *length" 44.Fa "int flags" 45.Fa "int ioflag" 46.Fa "struct ucred *active_cred" 47.Fa "struct ucred *file_cred" 48.Fc 49.Sh DESCRIPTION 50The 51.Fn vn_deallocate 52function zeros and/or deallocates backing storage space from a file. 53This function only works on vnodes with 54.Dv VREG 55type. 56.Pp 57The arguments are: 58.Bl -tag -width active_cred 59.It Fa vp 60The vnode of the file. 61.It Fa offset 62The starting offset of the operation range. 63.It Fa length 64The length of the operation range. 65This must be greater than 0. 66.It Fa flags 67The control flags of the operation. 68This should be set to 0 for now. 69.It Fa ioflag 70Directives and hints to be given to the file system. 71.It Fa active_cred 72The user credentials of the calling thread. 73.It Fa file_cred 74The credentials installed on the file description pointing to the vnode or NOCRED. 75.El 76.Pp 77The 78.Fn ioflag 79argument gives directives and hints to the file system. 80It may include one or more of the following flags: 81.Bl -tag -width IO_RANGELOCKED 82.It Dv IO_NODELOCKED 83The vnode was locked before the call. 84.It Dv IO_RANGELOCKED 85Rangelock was owned around the call. 86.It Dv IO_NOMACCHECK 87Skip MAC checking in the call. 88.It Dv IO_SYNC 89Do I/O synchronously. 90.It Dv IO_DIRECT 91Attempt to bypass buffer cache. 92.El 93.Pp 94.Fa *offset 95and 96.Fa *length 97are updated to reflect the unprocessed operation range of the call. 98For a successful completion, 99.Fa *length 100is updated to be the value 0, and 101.Fa *offset 102is incremented by the number of bytes zeroed before the end-of-file. 103.Sh RETURN VALUES 104Upon successful completion, the value 0 is returned; otherwise the 105appropriate error is returned. 106.Sh SEE ALSO 107.Xr vnode 9 , 108.Xr VOP_DEALLOCATE 9 109.Sh AUTHORS 110.Nm 111and this manual page was written by 112.An Ka Ho Ng Aq Mt khng@FreeBSD.org 113under sponsorship from the FreeBSD Foundation. 114