diff options
Diffstat (limited to '')
| -rw-r--r-- | sys-utils/fstrim.8 | 146 |
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/. |