| .TH FSTRIM 8 "July 2014" "util-linux" "System Administration" |
| .SH NAME |
| fstrim \- discard unused blocks on a mounted filesystem |
| .SH SYNOPSIS |
| .B fstrim |
| .RB [ \-a ] |
| .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, \-\-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 are silently |
| ignored. |
| .IP "\fB\-d, \-\-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\-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. 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 |
| .BR \-V , " \-\-version" |
| Display version information and exit. |
| .TP |
| .BR \-h , " \-\-help" |
| Display help text and exit. |
| |
| .SH RETURN CODES |
| .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 AUTHOR |
| .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/. |