1.\" 2.\" Copyright (c) 2019 Eugene Grosbein <eugen@FreeBSD.org>. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 13.\" 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 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd January 18, 2019 29.Dt TRIM 8 30.Os 31.Sh NAME 32.Nm trim 33.Nd erase device blocks that have no needed contents 34.Sh SYNOPSIS 35.Nm 36.Op Fl Nfqv 37.Fl [ [lo] Xo 38.Bk -words 39.Sm off 40.Ar offset 41.Op Cm K | k | M | m | G | g | T | t ] 42.Sm on 43.Xc 44.Ek 45.Bk -words 46.Op Fl r Ar rfile 47.Ek 48.Ar device ... 49.Sh DESCRIPTION 50The 51.Nm 52utility erases specified region of the device. 53It is mostly relevant for storage that implement trim (like flash based, 54or thinly provisioned storage). 55.Sy All erased data is lost. 56.Pp 57The following options are available: 58.Bl -tag -width indent 59.It Fl N 60Do not actually erase anything but show what it would do (dry run). 61Implies 62.Fl v . 63This is the default. 64Overrides 65.Fl f . 66.It Fl f 67Perform the operation. 68Overrides 69.Fl N . 70.It Fl l Xo 71.Sm off 72.Ar offset 73.Op Cm K | k | M | m | G | g | T | t 74.Sm on 75.Xc 76.It Fl o Xo 77.Sm off 78.Ar offset 79.Op Cm K | k | M | m | G | g | T | t 80.Sm on 81.Xc 82Specify the length 83.Fl l 84of the region to trim or its offset 85.Fl o 86from the beginning of the device. 87.Sy The whole device is erased by default 88unless one or both of these options are presented. 89.Pp 90The argument may be suffixed with one of 91.Cm K , 92.Cm M , 93.Cm G 94or 95.Cm T 96(either upper or lower case) to indicate a multiple of 97Kilobytes, Megabytes, Gigabytes or Terabytes 98respectively. 99.It Fl q 100Do not output anything except of possible error messages (quiet mode). 101Overrides 102.Fl v . 103.It Fl r Ar rfile 104Uses the length of given 105.Ar rfile 106as length of the region to erase. 107.Sy The whole device is erased by default. 108.It Fl v 109Show offset and length of actual region being erased, in bytes. 110.El 111.Pp 112Later options override previous ones. 113.Pp 114Note that actual success of the operation depends of underlying 115device driver such as 116.Xr ada 4 , 117.Xr da 4 118and others. 119Refer to corresponding manual pages for detail on possible caveats 120in low level support for ATA TRIM or SCSI UNMAP commands. 121.Sh EXIT STATUS 122.Ex -std 123If the final erase operation fails for an argument, the 124.Nm 125utility returns exit code 1. 126It can also return one of the exit codes defined in 127.Xr sysexits 3 , 128as follows: 129.Bl -tag -width ".Dv EX_UNAVAILABLE" 130.It Dv EX_USAGE 131The specified offset or length of the region is incorrect. 132.It Dv EX_OSERR 133There is no enough memory to proceed. 134.It Dv EX_NOINPUT 135The specified 136.Ar rfile 137cannot be opened (perhaps, it does not exist). 138.It Dv EX_IOERR 139The specified 140.Ar rfile 141cannot be examined for its size due to some system input/output error. 142.It Dv EX_DATAERR 143The specified 144.Ar rfile 145is not regular file, directory nor special device, so its size 146cannot be examined. 147.It Dv EX_UNAVAILABLE 148The specified 149.Ar rfile 150is special device file not supporting DIOCGMEDIASIZE 151.Xr ioctl 2 152(probably not a disk), so its size cannot be examined. 153.El 154.Sh SEE ALSO 155.Xr ioctl 2 , 156.Xr sysexits 3 , 157.Xr ada 4 , 158.Xr da 4 , 159.Xr nda 4 160.Sh HISTORY 161The 162.Nm 163utility first appeared in 164.Fx 12.1 . 165.Sh AUTHORS 166The 167.Nm 168utility was written by 169.An Eugene Grosbein Aq Mt eugen@FreeBSD.org . 170