svn commit: r341244 - head/usr.sbin/trim

[Eugene Grosbein]

Author: eugen
Date: Thu Nov 29 16:09:24 2018
New Revision: 341244
URL: https://svnweb.freebsd.org/changeset/base/341244

Log:
  Rename trim.1 to trim.8 too.
  
  MFC after:	1 month

Added:
  head/usr.sbin/trim/trim.8
     - copied unchanged from r341243, head/usr.sbin/trim/trim.1
Deleted:
  head/usr.sbin/trim/trim.1

Copied: head/usr.sbin/trim/trim.8 (from r341243, head/usr.sbin/trim/trim.1)
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/usr.sbin/trim/trim.8	Thu Nov 29 16:09:24 2018	(r341244, copy of r341243, head/usr.sbin/trim/trim.1)
@@ -0,0 +1,166 @@
+.\"
+.\" Copyright (c) 2018 Eugene Grosbein <eugen at FreeBSD.org>.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 29, 2018
+.Dt TRIM 1
+.Os
+.Sh NAME
+.Nm trim
+.Nd erase device blocks that have no needed contents
+.Sh SYNOPSIS
+.Nm
+.Op Fl Nfqv
+.Fl [ [lo] Xo
+.Bk -words
+.Sm off
+.Ar offset
+.Op Cm K | k | M | m | G | g | T | t ]
+.Sm on
+.Xc
+.Ek
+.Bk -words
+.Op Fl r Ar rfile
+.Ek
+.Ar device ...
+.Sh DESCRIPTION
+The
+.Nm
+utility erases specified region of the device.
+It is only relevant for flash based storage devices that use wear-leveling
+algorithms.
+.Sy All erased data is lost.
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl N
+Do not actually erase anything but show what it would do (dry run).
+Implies
+.Fl v .
+This is the default. Overrides
+.Fl f .
+.It Fl f
+Perform the operation. Overrides
+.Fl N .
+.It Fl l Xo
+.Sm off
+.Ar offset
+.Op Cm K | k | M | m | G | g | T | t
+.Sm on
+.Xc
+.It Fl o Xo
+.Sm off
+.Ar offset
+.Op Cm K | k | M | m | G | g | T | t
+.Sm on
+.Xc
+Specify the length
+.Fl l
+of the region to trim or its offset
+.Fl o
+from the beginning of the device.
+.Sy The whole device is erased by default
+unless one or both of these options are presented.
+.Pp
+The argument may be suffixed with one of
+.Cm K ,
+.Cm M ,
+.Cm G
+or
+.Cm T
+(either upper or lower case) to indicate a multiple of
+Kilobytes, Megabytes, Gigabytes or Terabytes
+respectively.
+.It Fl q
+Do not output anything except of possible error messages (quiet mode).
+Overrides
+.Fl v .
+.It Fl r Ar rfile
+Uses the length of given
+.Ar rfile
+as length of the region to erase.
+.Sy The whole device is erased by default.
+.It Fl v
+Show offset and length of actual region being erased, in bytes.
+.El
+.Pp
+Later options override previous ones.
+.Pp
+Note that actual success of the operation depends of underlying
+device driver such as
+.Xr ada 4 ,
+.Xr da 4
+and others.
+Refer to corresponding manual pages for detail on possible caveats
+in low level support for ATA TRIM or SCSI UNMAP commands.
+.Sh EXIT STATUS
+.Ex -std
+If the final erase operation fails for an argument, the
+.Nm
+utility returns exit code 1.
+It can also return one of the exit codes defined in
+.Xr sysexits 3 ,
+as follows:
+.Bl -tag -width ".Dv EX_UNAVAILABLE"
+.It Dv EX_USAGE
+The specified offset or length of the region is incorrect.
+.It Dv EX_OSERR
+There is no enough memory to proceed.
+.It Dv EX_NOINPUT
+The specified
+.Ar rfile
+cannot be opened (perhaps, it does not exist).
+.It Dv EX_IOERR
+The specified
+.Ar rfile
+cannot be examined for its size due to some system input/output error.
+.It Dv EX_DATAERR
+The specified
+.Ar rfile
+is not regular file, directory nor special device, so its size
+cannot be examined.
+.It Dv EX_UNAVAILABLE
+The specified
+.Ar rfile
+is special device file not supporting DIOCGMEDIASIZE
+.Xr ioctl 2
+(probably not a disk), so its size cannot be examined.
+.El
+.Sh SEE ALSO
+.Xr ada 4 ,
+.Xr da 4 ,
+.Xr ioctl 2 ,
+.Xr sysexits 3
+.Sh HISTORY
+The
+.Nm
+utility first appeared in
+.Fx 12.0 .
+.Sh AUTHORS
+The
+.Nm
+utility was written by
+.An Eugene Grosbein Aq Mt eugen at FreeBSD.org .