.\"	$NetBSD: blkdiscard.8,v 1.2 2022/10/15 21:53:21 andvar Exp $
.\"
.\" Copyright (c) 2022 Matthew R. Green
.\" All rights reserved.
.\"
.\" 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 ``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 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 February 6, 2022
.Dt BLKDISCARD 8
.Os
.Sh NAME
.Nm blkdiscard
.Nd tool to discard portions of a device or file
.Sh SYNOPSIS
.Nm
.Op Fl h
.Op Fl l Ar length
.Op Fl p Ar chunksize
.Op Fl n
.Op Fl o Ar firstbyte
.Op Fl R
.Op Fl s
.Op Fl V
.Op Fl v
.Op Fl z
.Ar file
.Nm fdiscard
.Op Fl f Ar firstbyte
.Op Fl h
.Op Fl l Ar length
.Op Fl m Ar chunksize
.Op Fl n
.Op Fl R
.Op Fl s
.Op Fl V
.Op Fl v
.Op Fl z
.Ar file
.Sh DESCRIPTION
The
.Nm
program can be used to discard portions of storage, and works on either
device files directly or upon files inside of a mounted file-system.
It provides access to the
.Xr fdiscard 2
system call, and relies upon the
backing device to have support in both the
.Nm
driver and in the hardware itself.
.Pp
The
.Nm fdiscard
interface defaults to the
.Dq no-run
mode and requires the
.Fl R
option to perform any actions.
.Pp
.Sh OPTIONS
Available options:
.Bl -tag -width chunksize123
.It Fl f Ar firstbyte
Set the first byte to be discarded.
The default is 0.
.It Fl h
Display built-in help.
.It Fl l Ar length
Limit the length to be discarded.
The default is the full device or file size, or the rest of the device
or file when the start offset has been set.
.It Fl m Ar chunksize
Set the per-operation chunksize.
The default is 32 MiB.
.It Fl n
Set the
.Dq no-run
option, and do not actually call
.Xr fdiscard 2 ,
secure erase, or write zeroes to the file.
.It Fl o Ar firstbyte
This flag is an alias for the
.Fl f
flag.
.It Fl p Ar chunksize
This flag is an alias for the
.Fl m
flag.
.It Fl R
Turn off the
.Dq no-run mode.
.It Fl s
Use secure erase operation.
This requires specific hardware support and is not currently supported.
.It Fl V
Display the program version and exit.
.It Fl v
Set the verbose flag.
.It Fl z
Write zeroes instead of calling
.Xr fdiscard 2 .
.Sh EXAMPLES
To have a dry-run cleaning of any particular file or device:
.Bd -literal -offset indent
# blkdiscard -n -v filename
# blkdiscard -n -v /dev/rwd0b
.Ed
.Pp
To discard all the blocks on a swap device:
.Bd -literal -offset indent
# blkdiscard -v /dev/rwd0b
.Ed
.Pp
To discard all but the first 256MiB of a device, using 128MiB increments:
.Bd -literal -offset indent
# blkdiscard -v -f 256m -m 128m /dev/rwd0c
.Ed
.Pp
To zero out the contents of a file or device:
.Bd -literal -offset indent
# blkdiscard -v -z filename
# blkdiscard -v -z /dev/device
.Ed
.Sh SEE ALSO
.Xr fdiscard 2
.Sh HISTORY
The
.Nm
command first appeared linux-util.
This implementation was originally called fdiscard-stuff and has been
converted to be
.Lx
.Xr blkdiscard 8
compatible and appeared in
.Nx 10.0 .
.Sh AUTHORS
The
.Nm
command was written by
.An Matthew R. Green
.Aq mrg@eterna.com.au .
.Sh BUGS
The secure erase functionality of the
.Fl s
option is not yet implemented.