1.\" $NetBSD: blkdiscard.8,v 1.3 2024/01/25 02:42:17 mrg Exp $ 2.\" 3.\" Copyright (c) 2022 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd January 13, 2024 28.Dt BLKDISCARD 8 29.Os 30.Sh NAME 31.Nm blkdiscard 32.Nd tool to discard portions of a device or file 33.Sh SYNOPSIS 34.Nm 35.Op Fl h 36.Op Fl l Ar length 37.Op Fl p Ar chunksize 38.Op Fl n 39.Op Fl o Ar firstbyte 40.Op Fl R 41.Op Fl s 42.Op Fl V 43.Op Fl v 44.Op Fl z 45.Ar file 46.Nm fdiscard 47.Op Fl f Ar firstbyte 48.Op Fl h 49.Op Fl l Ar length 50.Op Fl m Ar chunksize 51.Op Fl n 52.Op Fl R 53.Op Fl s 54.Op Fl V 55.Op Fl v 56.Op Fl z 57.Ar file 58.Sh DESCRIPTION 59The 60.Nm 61program can be used to discard portions of storage, and works on either 62device files directly or upon files inside of a mounted file-system. 63It provides access to the 64.Xr fdiscard 2 65system call, and relies upon the 66backing device to have support in both the 67.Nm 68driver and in the hardware itself. 69.Pp 70The 71.Nm fdiscard 72interface defaults to the 73.Dq no-run 74mode and requires the 75.Fl R 76option to perform any actions. 77.Pp 78.Sh OPTIONS 79Available options: 80.Bl -tag -width chunksize123 81.It Fl f Ar firstbyte 82Set the first byte to be discarded. 83The default is 0. 84.It Fl h 85Display built-in help. 86.It Fl l Ar length 87Limit the length to be discarded. 88The default is the full device or file size, or the rest of the device 89or file when the start offset has been set. 90.It Fl m Ar chunksize 91Set the per-operation chunksize. 92The default is 32 MiB. 93.It Fl n 94Set the 95.Dq no-run 96option, and do not actually call 97.Xr fdiscard 2 , 98secure erase, or write zeroes to the file. 99.It Fl o Ar firstbyte 100This flag is an alias for the 101.Fl f 102flag. 103.It Fl p Ar chunksize 104This flag is an alias for the 105.Fl m 106flag. 107.It Fl R 108Turn off the 109.Dq no-run mode. 110.It Fl s 111Use secure erase operation. 112This requires specific hardware support and is not currently supported. 113.It Fl V 114Display the program version and exit. 115.It Fl v 116Set the verbose flag. 117.It Fl z 118Write zeroes instead of calling 119.Xr fdiscard 2 . 120.Sh EXAMPLES 121To have a dry-run cleaning of any particular file or device: 122.Bd -literal -offset indent 123# blkdiscard -n -v filename 124# blkdiscard -n -v /dev/rwd0b 125.Ed 126.Pp 127To discard all the blocks on a swap device: 128.Bd -literal -offset indent 129# blkdiscard -v /dev/rwd0b 130.Ed 131.Pp 132To discard all but the first 256MiB of a device, using 128MiB increments: 133.Bd -literal -offset indent 134# blkdiscard -v -f 256m -m 128m /dev/rwd0c 135.Ed 136.Pp 137To zero out the contents of a file or device: 138.Bd -literal -offset indent 139# blkdiscard -v -z filename 140# blkdiscard -v -z /dev/device 141.Ed 142.Sh SEE ALSO 143.Xr fdiscard 2 144.Sh HISTORY 145The 146.Nm 147command first appeared linux-util. 148This implementation was originally called fdiscard-stuff and has been 149converted to be 150.Lx 151.Xr blkdiscard 8 152compatible and appeared in 153.Nx 10.0 . 154.Sh AUTHORS 155The 156.Nm 157command was written by 158.An Matthew R. Green 159.Aq mrg@eterna23.net . 160.Sh BUGS 161The secure erase functionality of the 162.Fl s 163option is not yet implemented. 164