fstrim: add new command

fstrim is used on a mounted filesystem to discard (or "trim") blocks
which are not in use by the filesystem.  This is useful for
solid-state drives (SSDs) and thinly-provisioned storage

Signed-off-by: Lukas Czerner <lczerner@redhat.com>
Signed-off-by: Karel Zak <kzak@redhat.com>

1 files changed, 84 insertions, 0 deletions

diff --git a/sys-utils/fstrim.8 b/sys-utils/fstrim.8
new file mode 100644
index 000000000..ae6ff8a10
--- /dev/null
+++ b/sys-utils/fstrim.8
@@ -0,0 +1,84 @@
+.\" -*- nroff -*-
+.TH FSTRIM 8 "Nov 2010"
+.SH NAME
+fstrim \- discard unused blocks on a mounted filesystem
+.SH SYNOPSIS
+.B fstrim
+.RB [ \-o
+.IR offset ]
+.RB [ \-l
+.IR length ]
+.RB [ \-m
+.IR minimum-extent ]
+.RB [ \-v ]
+.I mountpoint
+
+.SH DESCRIPTION
+.B fstrim
+is used on a mounted filesystem to discard (or "trim") blocks which are not in
+use by the filesystem.  This is useful for solid-state drives (SSDs) and
+thinly-provisioned storage.
+.PP
+By default,
+.B fstrim
+will discard all unused blocks in the filesystem.  Options may be used to
+modify this behavior based on range or size, as explained below.
+.PP
+The
+.I mountpoint
+argument is the pathname of the directory where the filesystem
+is mounted.
+
+.SH OPTIONS
+The \fIoffset\fR, \fIlength\fR, and \fIminimum-free-extent\fR arguments may be
+followed by binary (2^N) suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is
+optional, e.g. "K" has the same meaning as "KiB") or decimal (10^N) suffixes
+KB, MB, GB, PB and EB.
+.IP "\fB\-h, \-\-help\fP"
+Print help and exit.
+.IP "\fB\-o, \-\-offset\fP \fIoffset\fP"
+Byte offset in filesystem from which to begin searching for free blocks
+to discard.  Default value is zero, starting at the beginning of the
+filesystem.
+.IP "\fB\-l, \-\-length\fP \fIlength\fP"
+Number of bytes after starting point to search for free blocks to discard.
+If the specified value extends past the end of the filesystem,
+.B fstrim
+will stop at the filesystem size boundary. Default value extends to the end
+of the filesystem.
+.IP "\fB\-m, \-\-minimum\fP \fIminimum-free-extent\fP"
+Minimum contiguous free range to discard, in bytes. (This value is internally
+rounded up to a multiple of the filesystem block size).  Free ranges smaller
+than this will be ignored.  By increasing this value, the fstrim operation
+will complete more quickly for filesystems with badly fragmented freespace,
+although not all blocks will be discarded.  Default value is zero, discard
+every free block.
+.IP "\fB\-v, \-\-verbose\fP"
+Verbose execution. When specified 
+.B fstrim
+will output the number of bytes passed from the filesystem
+down the block stack to the device for potential discard. This number is a
+maximum discard amount from the storage device's perspective, because
+.I FITRIM
+ioctl called repeated will keep sending the same sectors for discard repeatedly.
+
+.B fstrim
+will report the same potential discard bytes each time, but only sectors which
+had been written to between the discards would actually be discarded by the
+storage device.  Further, the kernel block layer reserves the right to adjust
+the discard ranges to fit raid stripe geometry, non-trim capable devices in a
+LVM setup, etc.  These reductions would not be reflected in fstrim_range.len
+(the
+.B --length
+option).
+
+.SH AUTHOR
+.nf
+Lukas Czerner <lczerner@redhat.com>
+Karel Zak <kzak@redhat.com>
+.fi
+.SH SEE ALSO
+.BR mount (8)
+.SH AVAILABILITY
+The fstrim command is part of the util-linux-ng package and is available from
+ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.