1FSTRIM(8)                    System Administration                   FSTRIM(8)
2
3
4

NAME

6       fstrim - discard unused blocks on a mounted filesystem
7

SYNOPSIS

9       fstrim [-Aa] [-o offset] [-l length] [-m minimum-size] [-v] mountpoint
10
11

DESCRIPTION

13       fstrim  is  used  on a mounted filesystem to discard (or "trim") blocks
14       which are not in use by the filesystem.  This is useful for solid-state
15       drives (SSDs) and thinly-provisioned storage.
16
17       By  default,  fstrim  will discard all unused blocks in the filesystem.
18       Options may be used to modify this behavior based on range or size,  as
19       explained below.
20
21       The  mountpoint  argument  is  the  pathname of the directory where the
22       filesystem is mounted.
23
24       Running fstrim frequently, or even using mount -o discard, might  nega‐
25       tively affect the lifetime of poor-quality SSD devices.  For most desk‐
26       top and server systems a sufficient trimming frequency is once a  week.
27       Note  that  not all devices support a queued trim, so each trim command
28       incurs a performance penalty on whatever else might be  trying  to  use
29       the disk at the time.
30
31

OPTIONS

33       The  offset,  length, and minimum-size arguments may be followed by the
34       multiplicative suffixes KiB (=1024), MiB (=1024*1024), and  so  on  for
35       GiB,  TiB,  PiB,  EiB, ZiB and YiB (the "iB" is optional, e.g., "K" has
36       the same meaning as "KiB") or the suffixes KB (=1000), MB (=1000*1000),
37       and so on for GB, TB, PB, EB, ZB and YB.
38
39
40       -A, --fstab
41              Trim  all mounted filesystems mentioned in /etc/fstab on devices
42              that support the discard  operation.   The  root  filesystem  is
43              determined from kernel command line if missing in the file.  The
44              other supplied options, like --offset, --length  and  --minimum,
45              are  applied to all these devices.  Errors from filesystems that
46              do not support the  discard  operation,  read-only  devices  and
47              read-only filesystems are silently ignored.
48
49       -a, --all
50              Trim all mounted filesystems on devices that support the discard
51              operation.  The other supplied options, like --offset,  --length
52              and  --minimum,  are  applied to all these devices.  Errors from
53              filesystems that do not support the discard operation, read-only
54              devices and read-only filesystems are silently ignored.
55
56       -n, --dry-run
57              This  option  does  everything  apart  from actually call FITRIM
58              ioctl.
59
60       -o, --offset offset
61              Byte offset in the filesystem from which to begin searching  for
62              free  blocks to discard.  The default value is zero, starting at
63              the beginning of the filesystem.
64
65       -l, --length length
66              The number of bytes (after the starting  point)  to  search  for
67              free blocks to discard.  If the specified value extends past the
68              end of the filesystem, fstrim will stop at the  filesystem  size
69              boundary.   The default value extends to the end of the filesys‐
70              tem.
71
72       -m, --minimum minimum-size
73              Minimum contiguous free range to discard, in bytes. (This  value
74              is  internally  rounded up to a multiple of the filesystem block
75              size.)  Free ranges smaller than this will be ignored and fstrim
76              will  adjust the minimum if it's smaller than the device's mini‐
77              mum, and report that (fstrim_range.minlen)  back  to  userspace.
78              By  increasing  this  value,  the fstrim operation will complete
79              more quickly for filesystems with  badly  fragmented  freespace,
80              although not all blocks will be discarded.  The default value is
81              zero, discarding every free block.
82
83       -v, --verbose
84              Verbose execution.  With this option fstrim will output the num‐
85              ber  of bytes passed from the filesystem down the block stack to
86              the device for potential discard.  This number is a maximum dis‐
87              card  amount  from  the  storage  device's  perspective, because
88              FITRIM ioctl called repeated will keep sending the same  sectors
89              for discard repeatedly.
90
91              fstrim  will  report the same potential discard bytes each time,
92              but only sectors which had been written to between the  discards
93              would actually be discarded by the storage device.  Further, the
94              kernel block layer reserves the  right  to  adjust  the  discard
95              ranges  to fit raid stripe geometry, non-trim capable devices in
96              a LVM setup, etc.  These reductions would not  be  reflected  in
97              fstrim_range.len (the --length option).
98
99       --quiet
100              Suppress  trim operation (ioctl) error messages.  This option is
101              meant to be used in systemd service file or in cron  scripts  to
102              hide  warnings  that  are result of known problems, such as NTFS
103              driver reporting Bad file  descriptor  when  device  is  mounted
104              read-only, or lack of file system support for ioctl FITRIM call.
105
106       -V, --version
107              Display version information and exit.
108
109       -h, --help
110              Display help text and exit.
111
112

RETURN CODES

114       0      success
115
116       1      failure
117
118       32     all failed
119
120       64     some filesystem discards have succeeded, some failed
121
122       The  command fstrim --all returns 0 (all succeeded), 32 (all failed) or
123       64 (some failed, some succeeded).
124
125

AUTHOR

127       Lukas Czerner <lczerner@redhat.com>
128       Karel Zak <kzak@redhat.com>
129

SEE ALSO

131       blkdiscard(8), mount(8)
132

AVAILABILITY

134       The fstrim command is part of the util-linux package and  is  available
135       from https://www.kernel.org/pub/linux/utils/util-linux/.
136
137
138
139util-linux                         May 2019                          FSTRIM(8)
Impressum