]>
Commit | Line | Data |
---|---|---|
374baa6f | 1 | .TH FSTRIM 8 "May 2019" "util-linux" "System Administration" |
d9e2d0dd LC |
2 | .SH NAME |
3 | fstrim \- discard unused blocks on a mounted filesystem | |
4 | .SH SYNOPSIS | |
5 | .B fstrim | |
c5b8909f | 6 | .RB [ \-Aa ] |
d9e2d0dd LC |
7 | .RB [ \-o |
8 | .IR offset ] | |
9 | .RB [ \-l | |
10 | .IR length ] | |
11 | .RB [ \-m | |
c372860d | 12 | .IR minimum-size ] |
d9e2d0dd LC |
13 | .RB [ \-v ] |
14 | .I mountpoint | |
15 | ||
16 | .SH DESCRIPTION | |
17 | .B fstrim | |
18 | is used on a mounted filesystem to discard (or "trim") blocks which are not in | |
19 | use by the filesystem. This is useful for solid-state drives (SSDs) and | |
20 | thinly-provisioned storage. | |
21 | .PP | |
22 | By default, | |
23 | .B fstrim | |
24 | will discard all unused blocks in the filesystem. Options may be used to | |
25 | modify this behavior based on range or size, as explained below. | |
26 | .PP | |
27 | The | |
28 | .I mountpoint | |
29 | argument is the pathname of the directory where the filesystem | |
30 | is mounted. | |
004ff2d6 KZ |
31 | .PP |
32 | Running | |
33 | .B fstrim | |
c372860d | 34 | frequently, or even using |
1c4c6024 | 35 | .BR "mount \-o discard" , |
c372860d | 36 | might negatively affect the lifetime of poor-quality SSD devices. For most |
bbe6f3cf | 37 | desktop and server systems a sufficient trimming frequency is once a week. |
c372860d BS |
38 | Note that not all |
39 | devices support a queued trim, so each trim command incurs a performance penalty | |
40 | on whatever else might be trying to use the disk at the time. | |
d9e2d0dd LC |
41 | |
42 | .SH OPTIONS | |
c372860d BS |
43 | The \fIoffset\fR, \fIlength\fR, and \fIminimum-size\fR arguments may be |
44 | followed by the multiplicative suffixes KiB (=1024), | |
45 | MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" | |
46 | is optional, e.g., "K" has the same meaning as "KiB") or the suffixes | |
47 | KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB. | |
48 | ||
c5b8909f KZ |
49 | .IP "\fB\-A, \-\-fstab\fP" |
50 | Trim all mounted filesystems mentioned in \fI/etc/fstab\fR on devices that support the | |
410d12e5 KZ |
51 | discard operation. The root filesystem is determined from kernel command line if missing |
52 | in the file. | |
c5b8909f KZ |
53 | The other supplied options, like \fB\-\-offset\fR, \fB\-\-length\fR and |
54 | \fB-\-minimum\fR, are applied to all these devices. | |
6466959d KZ |
55 | Errors from filesystems that do not support the discard operation, |
56 | read-only devices and read-only filesystems are silently ignored. | |
36c370cb | 57 | .IP "\fB\-a, \-\-all\fP" |
d6bbe804 BS |
58 | Trim all mounted filesystems on devices that support the discard operation. |
59 | The other supplied options, like \fB\-\-offset\fR, \fB\-\-length\fR and | |
60 | \fB-\-minimum\fR, are applied to all these devices. | |
6466959d KZ |
61 | Errors from filesystems that do not support the discard operation, |
62 | read-only devices and read-only filesystems are silently ignored. | |
26b6525a | 63 | .IP "\fB\-n, \-\-dry\-run\fP" |
fda0e2cf | 64 | This option does everything apart from actually call FITRIM ioctl. |
d9e2d0dd | 65 | .IP "\fB\-o, \-\-offset\fP \fIoffset\fP" |
c372860d BS |
66 | Byte offset in the filesystem from which to begin searching for free blocks |
67 | to discard. The default value is zero, starting at the beginning of the | |
d9e2d0dd LC |
68 | filesystem. |
69 | .IP "\fB\-l, \-\-length\fP \fIlength\fP" | |
c372860d BS |
70 | The number of bytes (after the starting point) to search for free blocks |
71 | to discard. If the specified value extends past the end of the filesystem, | |
d9e2d0dd | 72 | .B fstrim |
c372860d BS |
73 | will stop at the filesystem size boundary. The default value extends to |
74 | the end of the filesystem. | |
75 | .IP "\fB\-m, \-\-minimum\fP \fIminimum-size\fP" | |
d9e2d0dd | 76 | Minimum contiguous free range to discard, in bytes. (This value is internally |
bbe6f3cf | 77 | rounded up to a multiple of the filesystem block size.) Free ranges smaller |
ce3d198d WS |
78 | than this will be ignored and fstrim will adjust the minimum if it's smaller than |
79 | the device's minimum, and report that (fstrim_range.minlen) back to userspace. | |
80 | By increasing this value, the fstrim operation will complete more quickly for | |
81 | filesystems with badly fragmented freespace, although not all blocks will be | |
82 | discarded. The default value is zero, discarding every free block. | |
d9e2d0dd | 83 | .IP "\fB\-v, \-\-verbose\fP" |
c372860d | 84 | Verbose execution. With this option |
d9e2d0dd LC |
85 | .B fstrim |
86 | will output the number of bytes passed from the filesystem | |
c372860d | 87 | down the block stack to the device for potential discard. This number is a |
d9e2d0dd LC |
88 | maximum discard amount from the storage device's perspective, because |
89 | .I FITRIM | |
90 | ioctl called repeated will keep sending the same sectors for discard repeatedly. | |
c372860d | 91 | .sp |
d9e2d0dd LC |
92 | .B fstrim |
93 | will report the same potential discard bytes each time, but only sectors which | |
94 | had been written to between the discards would actually be discarded by the | |
95 | storage device. Further, the kernel block layer reserves the right to adjust | |
96 | the discard ranges to fit raid stripe geometry, non-trim capable devices in a | |
97 | LVM setup, etc. These reductions would not be reflected in fstrim_range.len | |
98 | (the | |
1c4c6024 | 99 | .B \-\-length |
d9e2d0dd | 100 | option). |
c372860d | 101 | .TP |
ef89802e KZ |
102 | .B \-\-quiet\-unsupported |
103 | Suppress error messages if trim operation (ioctl) is unsupported. This option | |
104 | is meant to be used in systemd service file or in cron scripts to hide warnings | |
105 | that are result of known problems, | |
6466959d | 106 | such as NTFS driver |
374baa6f SK |
107 | reporting |
108 | .I Bad file descriptor | |
109 | when device is mounted read-only, or lack of file system support for ioctl | |
110 | FITRIM call. | |
111 | .TP | |
c372860d BS |
112 | .BR \-V , " \-\-version" |
113 | Display version information and exit. | |
114 | .TP | |
115 | .BR \-h , " \-\-help" | |
116 | Display help text and exit. | |
d9e2d0dd | 117 | |
7e765c93 | 118 | .SH EXIT STATUS |
36c370cb KZ |
119 | .IP 0 |
120 | success | |
121 | .IP 1 | |
122 | failure | |
123 | .IP 32 | |
124 | all failed | |
125 | .IP 64 | |
d6bbe804 | 126 | some filesystem discards have succeeded, some failed |
36c370cb KZ |
127 | .PP |
128 | The command | |
1c4c6024 | 129 | .B fstrim \-\-all |
c372860d | 130 | returns 0 (all succeeded), 32 (all failed) or 64 (some failed, some succeeded). |
36c370cb | 131 | |
a8d0d330 | 132 | .SH AUTHORS |
d9e2d0dd LC |
133 | .nf |
134 | Lukas Czerner <lczerner@redhat.com> | |
135 | Karel Zak <kzak@redhat.com> | |
136 | .fi | |
137 | .SH SEE ALSO | |
f053ff1e MK |
138 | .BR blkdiscard (8), |
139 | .BR mount (8) | |
d9e2d0dd | 140 | .SH AVAILABILITY |
601d12fb | 141 | The fstrim command is part of the util-linux package and is available from |
d673b74e | 142 | https://www.kernel.org/pub/linux/utils/util-linux/. |