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.Dd July 20, 2025 27.Dt TRIM 8 28.Os 29.Sh NAME 30.Nm trim 31.Nd erase device blocks that have no needed contents 32.Sh SYNOPSIS 33.Nm 34.Op Fl Nfqv 35.Fl [ [lo] Xo 36.Bk -words 37.Sm off 38.Ar offset 39.Op Cm K | k | M | m | G | g | T | t | P | p | E | e ] 40.Sm on 41.Xc 42.Ek 43.Bk -words 44.Op Fl r Ar rfile 45.Ek 46.Ar device ... 47.Sh DESCRIPTION 48The 49.Nm 50utility erases specified region of the device. 51It is mostly relevant for storage that implement trim (like flash based, 52or thinly provisioned storage). 53.Sy All erased data is lost. 54.Pp 55The following options are available: 56.Bl -tag -width indent 57.It Fl N 58Do not actually erase anything but show what it would do (dry run). 59Implies 60.Fl v . 61This is the default. 62Overrides 63.Fl f . 64.It Fl f 65Perform the operation. 66Overrides 67.Fl N . 68.It Fl l Xo 69.Sm off 70.Ar offset 71.Op Cm K | k | M | m | G | g | T | t | P | p | E | e 72.Sm on 73.Xc 74.It Fl o Xo 75.Sm off 76.Ar offset 77.Op Cm K | k | M | m | G | g | T | t | P | p | E | e 78.Sm on 79.Xc 80Specify the length 81.Fl l 82of the region to trim or its offset 83.Fl o 84from the beginning of the device. 85.Sy The whole device is erased by default 86unless one or both of these options are presented. 87.Pp 88The argument may be suffixed with one of 89.Cm K , 90.Cm M , 91.Cm G , 92.Cm T , 93.Cm P 94or 95.Cm E 96(either upper or lower case) to indicate a multiple of 97Kilobytes, Megabytes, Gigabytes, Terabytes, Petabytes or 98Exabytes, respectively. 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