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).
63 This is the default. Overrides
66 Perform the operation. Overrides
71 .Op Cm K | k | M | m | G | g | T | t
77 .Op Cm K | k | M | m | G | g | T | t
82 of the region to trim or its offset
84 from the beginning of the device.
85 .Sy The whole device is erased by default
86 unless one or both of these options are presented.
88 The argument may be suffixed with one of
94 (either upper or lower case) to indicate a multiple of
95 Kilobytes, Megabytes, Gigabytes or Terabytes
98 Do not output anything except of possible error messages (quiet mode).
102 Uses the length of given
104 as length of the region to erase.
105 .Sy The whole device is erased by default.
107 Show offset and length of actual region being erased, in bytes.
110 Later options override previous ones.
112 Note that actual success of the operation depends of underlying
113 device driver such as
117 Refer to corresponding manual pages for detail on possible caveats
118 in low level support for ATA TRIM or SCSI UNMAP commands.
121 If the final erase operation fails for an argument, the
123 utility returns exit code 1.
124 It can also return one of the exit codes defined in
127 .Bl -tag -width ".Dv EX_UNAVAILABLE"
129 The specified offset or length of the region is incorrect.
131 There is no enough memory to proceed.
135 cannot be opened (perhaps, it does not exist).
139 cannot be examined for its size due to some system input/output error.
143 is not regular file, directory nor special device, so its size
145 .It Dv EX_UNAVAILABLE
148 is special device file not supporting DIOCGMEDIASIZE
150 (probably not a disk), so its size cannot be examined.
161 utility first appeared in
166 utility was written by
167 .An Eugene Grosbein Aq Mt eugen@FreeBSD.org .