[thirdparty/util-linux.git] / sys-utils / fstrim.8

.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\-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/.
Commit	Line	Data
c372860d	1	.TH FSTRIM 8 "July 2014" "util-linux" "System Administration"
d9e2d0dd LC	2	.SH NAME
	3	fstrim \- discard unused blocks on a mounted filesystem
	4	.SH SYNOPSIS
	5	.B fstrim
36c370cb	6	.RB [ \-a ]
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 BS	34	frequently, or even using
	35	.BR "mount -o discard" ,
	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
d9e2d0dd LC	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
36c370cb	49	.IP "\fB\-a, \-\-all\fP"
d6bbe804 BS	50	Trim all mounted filesystems on devices that support the discard operation.
	51	The other supplied options, like \fB\-\-offset\fR, \fB\-\-length\fR and
	52	\fB-\-minimum\fR, are applied to all these devices.
	53	Errors from filesystems that do not support the discard operation are silently
36c370cb	54	ignored.
d9e2d0dd	55	.IP "\fB\-o, \-\-offset\fP \fIoffset\fP"
c372860d BS	56	Byte offset in the filesystem from which to begin searching for free blocks
c372860d BS	57	to discard. The default value is zero, starting at the beginning of the
d9e2d0dd LC	58	filesystem.
d9e2d0dd LC	59	.IP "\fB\-l, \-\-length\fP \fIlength\fP"
c372860d BS	60	The number of bytes (after the starting point) to search for free blocks
c372860d BS	61	to discard. If the specified value extends past the end of the filesystem,
d9e2d0dd	62	.B fstrim
c372860d BS	63	will stop at the filesystem size boundary. The default value extends to
	64	the end of the filesystem.
	65	.IP "\fB\-m, \-\-minimum\fP \fIminimum-size\fP"
d9e2d0dd	66	Minimum contiguous free range to discard, in bytes. (This value is internally
bbe6f3cf	67	rounded up to a multiple of the filesystem block size.) Free ranges smaller
d9e2d0dd LC	68	than this will be ignored. By increasing this value, the fstrim operation
d9e2d0dd LC	69	will complete more quickly for filesystems with badly fragmented freespace,
bbe6f3cf BS	70	although not all blocks will be discarded. The default value is zero,
bbe6f3cf BS	71	discarding every free block.
d9e2d0dd	72	.IP "\fB\-v, \-\-verbose\fP"
c372860d	73	Verbose execution. With this option
d9e2d0dd LC	74	.B fstrim
d9e2d0dd LC	75	will output the number of bytes passed from the filesystem
c372860d	76	down the block stack to the device for potential discard. This number is a
d9e2d0dd LC	77	maximum discard amount from the storage device's perspective, because
	78	.I FITRIM
	79	ioctl called repeated will keep sending the same sectors for discard repeatedly.
c372860d	80	.sp
d9e2d0dd LC	81	.B fstrim
	82	will report the same potential discard bytes each time, but only sectors which
	83	had been written to between the discards would actually be discarded by the
	84	storage device. Further, the kernel block layer reserves the right to adjust
	85	the discard ranges to fit raid stripe geometry, non-trim capable devices in a
	86	LVM setup, etc. These reductions would not be reflected in fstrim_range.len
	87	(the
	88	.B --length
	89	option).
c372860d BS	90	.TP
	91	.BR \-V , " \-\-version"
	92	Display version information and exit.
	93	.TP
	94	.BR \-h , " \-\-help"
	95	Display help text and exit.
d9e2d0dd	96
36c370cb KZ	97	.SH RETURN CODES
	98	.IP 0
	99	success
	100	.IP 1
	101	failure
	102	.IP 32
	103	all failed
	104	.IP 64
d6bbe804	105	some filesystem discards have succeeded, some failed
36c370cb KZ	106	.PP
	107	The command
	108	.B fstrim --all
c372860d	109	returns 0 (all succeeded), 32 (all failed) or 64 (some failed, some succeeded).
36c370cb	110
d9e2d0dd LC	111	.SH AUTHOR
	112	.nf
	113	Lukas Czerner <lczerner@redhat.com>
	114	Karel Zak <kzak@redhat.com>
	115	.fi
	116	.SH SEE ALSO
f053ff1e MK	117	.BR blkdiscard (8),
f053ff1e MK	118	.BR mount (8)
d9e2d0dd	119	.SH AVAILABILITY
601d12fb	120	The fstrim command is part of the util-linux package and is available from
d673b74e	121	https://www.kernel.org/pub/linux/utils/util-linux/.