2 .\" Copyright (c) 2019 Eugene Grosbein <eugen@FreeBSD.org>.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd erase device blocks that have no needed contents
41 .Op Cm K | k | M | m | G | g | T | t ]
52 utility erases specified region of the device.
53 It is mostly relevant for storage that implement trim (like flash based,
54 or thinly provisioned storage).
55 .Sy All erased data is lost.
57 The following options are available:
58 .Bl -tag -width indent
60 Do not actually erase anything but show what it would do (dry run).
67 Perform the operation.
73 .Op Cm K | k | M | m | G | g | T | t
79 .Op Cm K | k | M | m | G | g | T | t
84 of the region to trim or its offset
86 from the beginning of the device.
87 .Sy The whole device is erased by default
88 unless one or both of these options are presented.
90 The argument may be suffixed with one of
96 (either upper or lower case) to indicate a multiple of
97 Kilobytes, Megabytes, Gigabytes or Terabytes
100 Do not output anything except of possible error messages (quiet mode).
104 Uses the length of given
106 as length of the region to erase.
107 .Sy The whole device is erased by default.
109 Show offset and length of actual region being erased, in bytes.
112 Later options override previous ones.
114 Note that actual success of the operation depends of underlying
115 device driver such as
119 Refer to corresponding manual pages for detail on possible caveats
120 in low level support for ATA TRIM or SCSI UNMAP commands.
123 If the final erase operation fails for an argument, the
125 utility returns exit code 1.
126 It can also return one of the exit codes defined in
129 .Bl -tag -width ".Dv EX_UNAVAILABLE"
131 The specified offset or length of the region is incorrect.
133 There is no enough memory to proceed.
137 cannot be opened (perhaps, it does not exist).
141 cannot be examined for its size due to some system input/output error.
145 is not regular file, directory nor special device, so its size
147 .It Dv EX_UNAVAILABLE
150 is special device file not supporting DIOCGMEDIASIZE
152 (probably not a disk), so its size cannot be examined.
163 utility first appeared in
168 utility was written by
169 .An Eugene Grosbein Aq Mt eugen@FreeBSD.org .