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. Overrides 64.Fl f . 65.It Fl f 66Perform the operation. Overrides 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 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 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 92or 93.Cm T 94(either upper or lower case) to indicate a multiple of 95Kilobytes, Megabytes, Gigabytes or Terabytes 96respectively. 97.It Fl q 98Do not output anything except of possible error messages (quiet mode). 99Overrides 100.Fl v . 101.It Fl r Ar rfile 102Uses the length of given 103.Ar rfile 104as length of the region to erase. 105.Sy The whole device is erased by default. 106.It Fl v 107Show offset and length of actual region being erased, in bytes. 108.El 109.Pp 110Later options override previous ones. 111.Pp 112Note that actual success of the operation depends of underlying 113device driver such as 114.Xr ada 4 , 115.Xr da 4 116and others. 117Refer to corresponding manual pages for detail on possible caveats 118in low level support for ATA TRIM or SCSI UNMAP commands. 119.Sh EXIT STATUS 120.Ex -std 121If the final erase operation fails for an argument, the 122.Nm 123utility returns exit code 1. 124It can also return one of the exit codes defined in 125.Xr sysexits 3 , 126as follows: 127.Bl -tag -width ".Dv EX_UNAVAILABLE" 128.It Dv EX_USAGE 129The specified offset or length of the region is incorrect. 130.It Dv EX_OSERR 131There is no enough memory to proceed. 132.It Dv EX_NOINPUT 133The specified 134.Ar rfile 135cannot be opened (perhaps, it does not exist). 136.It Dv EX_IOERR 137The specified 138.Ar rfile 139cannot be examined for its size due to some system input/output error. 140.It Dv EX_DATAERR 141The specified 142.Ar rfile 143is not regular file, directory nor special device, so its size 144cannot be examined. 145.It Dv EX_UNAVAILABLE 146The specified 147.Ar rfile 148is special device file not supporting DIOCGMEDIASIZE 149.Xr ioctl 2 150(probably not a disk), so its size cannot be examined. 151.El 152.Sh SEE ALSO 153.Xr ada 4 , 154.Xr da 4 , 155.Xr ioctl 2 , 156.Xr nda 4 , 157.Xr sysexits 3 158.Sh HISTORY 159The 160.Nm 161utility first appeared in 162.Fx 12.1 . 163.Sh AUTHORS 164The 165.Nm 166utility was written by 167.An Eugene Grosbein Aq Mt eugen@FreeBSD.org . 168