usr.sbin/trim/trim.8

   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
  50 The
  51 .Nm
  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.
  56 .Pp
  57 The following options are available:
  58 .Bl -tag -width indent
  59 .It Fl N
  60 Do not actually erase anything but show what it would do (dry run).
  61 Implies
  62 .Fl v .
  63 This is the default.
  64 Overrides
  65 .Fl f .
  66 .It Fl f
  67 Perform the operation.
  68 Overrides
  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
  82 Specify the length
  83 .Fl l
  84 of the region to trim or its offset
  85 .Fl o
  86 from the beginning of the device.
  87 .Sy The whole device is erased by default
  88 unless one or both of these options are presented.
  89 .Pp
  90 The argument may be suffixed with one of
  91 .Cm K ,
  92 .Cm M ,
  93 .Cm G
  94 or
  95 .Cm T
  96 (either upper or lower case) to indicate a multiple of
  97 Kilobytes, Megabytes, Gigabytes or Terabytes
  98 respectively.
  99 .It Fl q
 100 Do not output anything except of possible error messages (quiet mode).
 101 Overrides
 102 .Fl v .
 103 .It Fl r Ar rfile
 104 Uses the length of given
 105 .Ar rfile
 106 as length of the region to erase.
 107 .Sy The whole device is erased by default.
 108 .It Fl v
 109 Show offset and length of actual region being erased, in bytes.
 110 .El
 111 .Pp
 112 Later options override previous ones.
 113 .Pp
 114 Note that actual success of the operation depends of underlying
 115 device driver such as
 116 .Xr ada 4 ,
 117 .Xr da 4
 118 and others.
 119 Refer to corresponding manual pages for detail on possible caveats
 120 in low level support for ATA TRIM or SCSI UNMAP commands.
 121 .Sh EXIT STATUS
 122 .Ex -std
 123 If the final erase operation fails for an argument, the
 124 .Nm
 125 utility returns exit code 1.
 126 It can also return one of the exit codes defined in
 127 .Xr sysexits 3 ,
 128 as follows:
 129 .Bl -tag -width ".Dv EX_UNAVAILABLE"
 130 .It Dv EX_USAGE
 131 The specified offset or length of the region is incorrect.
 132 .It Dv EX_OSERR
 133 There is no enough memory to proceed.
 134 .It Dv EX_NOINPUT
 135 The specified
 136 .Ar rfile
 137 cannot be opened (perhaps, it does not exist).
 138 .It Dv EX_IOERR
 139 The specified
 140 .Ar rfile
 141 cannot be examined for its size due to some system input/output error.
 142 .It Dv EX_DATAERR
 143 The specified
 144 .Ar rfile
 145 is not regular file, directory nor special device, so its size
 146 cannot be examined.
 147 .It Dv EX_UNAVAILABLE
 148 The specified
 149 .Ar rfile
 150 is 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
 161 The
 162 .Nm
 163 utility first appeared in
 164 .Fx 12.1 .
 165 .Sh AUTHORS
 166 The
 167 .Nm
 168 utility was written by
 169 .An Eugene Grosbein Aq Mt eugen@FreeBSD.org .