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 October 1, 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 a storage that implements trim (like flash based, 52or thinly provisioned storage). 53.Sy All erased data is lost. 54Alternatively, refer to the 55.Xr fsck_ffs 8 56command having a flag 57.Fl E 58to trim populated UFS, and to the 59.Xr zpool-trim 8 60command to trim existing ZFS pool. 61.Pp 62The following options are available: 63.Bl -tag -width indent 64.It Fl N 65Do not actually erase anything but show what it would do (dry run). 66Implies 67.Fl v . 68This is the default. 69Overrides 70.Fl f . 71.It Fl f 72Perform the operation. 73Overrides 74.Fl N . 75.It Fl l Xo 76.Sm off 77.Ar offset 78.Op Cm K | k | M | m | G | g | T | t | P | p | E | e 79.Sm on 80.Xc 81.It Fl o Xo 82.Sm off 83.Ar offset 84.Op Cm K | k | M | m | G | g | T | t | P | p | E | e 85.Sm on 86.Xc 87Specify the length 88.Fl l 89of the region to trim or its offset 90.Fl o 91from the beginning of the device. 92.Sy The whole device is erased by default 93unless one or both of these options are presented. 94.Pp 95The argument may be suffixed with one of 96.Cm K , 97.Cm M , 98.Cm G , 99.Cm T , 100.Cm P 101or 102.Cm E 103(either upper or lower case) to indicate a multiple of 104Kilobytes, Megabytes, Gigabytes, Terabytes, Petabytes or 105Exabytes, respectively. 106.It Fl q 107Do not output anything except of possible error messages (quiet mode). 108Overrides 109.Fl v . 110.It Fl r Ar rfile 111Uses the length of given 112.Ar rfile 113as length of the region to erase. 114.Sy The whole device is erased by default. 115.It Fl v 116Show offset and length of actual region being erased, in bytes. 117.El 118.Pp 119Later options override previous ones. 120.Pp 121Note that actual success of the operation depends of underlying 122device driver such as 123.Xr ada 4 , 124.Xr da 4 125and others. 126Refer to corresponding manual pages for detail on possible caveats 127in low level support for ATA TRIM or SCSI UNMAP commands. 128.Sh EXIT STATUS 129.Ex -std 130If the final erase operation fails for an argument, the 131.Nm 132utility returns exit code 1. 133It can also return one of the exit codes defined in 134.Xr sysexits 3 , 135as follows: 136.Bl -tag -width ".Dv EX_UNAVAILABLE" 137.It Dv EX_USAGE 138The specified offset or length of the region is incorrect. 139.It Dv EX_OSERR 140There is no enough memory to proceed. 141.It Dv EX_NOINPUT 142The specified 143.Ar rfile 144cannot be opened (perhaps, it does not exist). 145.It Dv EX_IOERR 146The specified 147.Ar rfile 148cannot be examined for its size due to some system input/output error. 149.It Dv EX_DATAERR 150The specified 151.Ar rfile 152is not regular file, directory nor special device, so its size 153cannot be examined. 154.It Dv EX_UNAVAILABLE 155The specified 156.Ar rfile 157is special device file not supporting DIOCGMEDIASIZE 158.Xr ioctl 2 159(probably not a disk), so its size cannot be examined. 160.El 161.Sh SEE ALSO 162.Xr ioctl 2 , 163.Xr sysexits 3 , 164.Xr ada 4 , 165.Xr da 4 , 166.Xr nda 4 , 167.Xr fsck_ffs 8 , 168.Xr zpool-trim 8 169.Sh HISTORY 170The 171.Nm 172utility first appeared in 173.Fx 12.1 . 174.Sh AUTHORS 175The 176.Nm 177utility was written by 178.An Eugene Grosbein Aq Mt eugen@FreeBSD.org . 179