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