147 lines
5.5 KiB
Groff
147 lines
5.5 KiB
Groff
.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/.
|