Adding upstream version 2.36.1.upstream/2.36.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 146 insertions, 0 deletions

diff --git a/sys-utils/fstrim.8 b/sys-utils/fstrim.8
new file mode 100644
index 0000000..52199eb
--- /dev/null
+++ b/sys-utils/fstrim.8
@@ -0,0 +1,146 @@
+.TH FSTRIM 8 "May 2019" "util-linux" "System Administration"
+.SH NAME
+fstrim \- discard unused blocks on a mounted filesystem
+.SH SYNOPSIS
+.B fstrim
+.RB [ \-Aa ]
+.RB [ \-o
+.IR offset ]
+.RB [ \-l
+.IR length ]
+.RB [ \-m
+.IR minimum-size ]
+.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.
+.PP
+Running
+.B fstrim
+frequently, or even using
+.BR "mount \-o discard" ,
+might negatively affect the lifetime of poor-quality SSD devices.  For most
+desktop and server systems a sufficient trimming frequency is once a week.
+Note that not all
+devices support a queued trim, so each trim command incurs a performance penalty
+on whatever else might be trying to use the disk at the time.
+
+.SH OPTIONS
+The \fIoffset\fR, \fIlength\fR, and \fIminimum-size\fR arguments may be
+followed by the multiplicative suffixes KiB (=1024),
+MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB"
+is optional, e.g., "K" has the same meaning as "KiB") or the suffixes
+KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
+
+.IP "\fB\-A, \-\-fstab\fP"
+Trim all mounted filesystems mentioned in \fI/etc/fstab\fR on devices that support the
+discard operation.  The root filesystem is determined from kernel command line if missing
+in the file.
+The other supplied options, like \fB\-\-offset\fR, \fB\-\-length\fR and
+\fB-\-minimum\fR, are applied to all these devices.
+Errors from filesystems that do not support the discard operation,
+read-only devices and read-only filesystems are silently ignored.
+.IP "\fB\-a, \-\-all\fP"
+Trim all mounted filesystems on devices that support the discard operation.
+The other supplied options, like \fB\-\-offset\fR, \fB\-\-length\fR and
+\fB-\-minimum\fR, are applied to all these devices.
+Errors from filesystems that do not support the discard operation,
+read-only devices and read-only filesystems are silently ignored.
+.IP "\fB\-n, \-\-dry\-run\fP"
+This option does everything apart from actually call FITRIM ioctl.
+.IP "\fB\-o, \-\-offset\fP \fIoffset\fP"
+Byte offset in the filesystem from which to begin searching for free blocks
+to discard.  The default value is zero, starting at the beginning of the
+filesystem.
+.IP "\fB\-l, \-\-length\fP \fIlength\fP"
+The number of bytes (after the 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.  The default value extends to
+the end of the filesystem.
+.IP "\fB\-I, \-\-listed\-in\fP \fIlist\fP"
+Specifies a colon-separated list of files in fstab or kernel mountinfo
+format. All missing or empty files are silently ignored.  The evaluation of the
+\fIlist\fP stops after first non-empty file. For example: \fB--listed-in /etc/fstab:/proc/self/mountinfo\fR.
+.IP "\fB\-m, \-\-minimum\fP \fIminimum-size\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 and fstrim will adjust the minimum if it's smaller than
+the device's minimum, and report that (fstrim_range.minlen) back to userspace.
+By increasing this value, the fstrim operation will complete more quickly for
+filesystems with badly fragmented freespace, although not all blocks will be
+discarded.  The default value is zero, discarding every free block.
+.IP "\fB\-v, \-\-verbose\fP"
+Verbose execution.  With this option
+.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.
+.sp
+.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).
+.TP
+.B \-\-quiet\-unsupported
+Suppress error messages if trim operation (ioctl) is unsupported.  This option
+is meant to be used in systemd service file or in cron scripts to hide warnings
+that are result of known problems,
+such as NTFS driver
+reporting
+.I Bad file descriptor
+when device is mounted read-only, or lack of file system support for ioctl
+FITRIM call.
+.TP
+.BR \-V , " \-\-version"
+Display version information and exit.
+.TP
+.BR \-h , " \-\-help"
+Display help text and exit.
+
+.SH EXIT STATUS
+.IP 0
+success
+.IP 1
+failure
+.IP 32
+all failed
+.IP 64
+some filesystem discards have succeeded, some failed
+.PP
+The command
+.B fstrim \-\-all
+returns 0 (all succeeded), 32 (all failed) or 64 (some failed, some succeeded).
+
+.SH AUTHORS
+.nf
+Lukas Czerner <lczerner@redhat.com>
+Karel Zak <kzak@redhat.com>
+.fi
+.SH SEE ALSO
+.BR blkdiscard (8),
+.BR mount (8)
+.SH AVAILABILITY
+The fstrim command is part of the util-linux package and is available from
+https://www.kernel.org/pub/linux/utils/util-linux/.