From: Lukas Czerner Date: Wed, 24 Nov 2010 23:05:37 +0000 (+0100) Subject: fstrim: add new command X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d9e2d0dd144c2c06bff590c35400965016e55b7c;p=util-linux fstrim: add new command 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 Signed-off-by: Lukas Czerner Signed-off-by: Karel Zak --- diff --git a/sys-utils/.gitignore b/sys-utils/.gitignore index 7af5ffbf..b8af98f1 100644 --- a/sys-utils/.gitignore +++ b/sys-utils/.gitignore @@ -5,6 +5,7 @@ dmesg fallocate flock fsfreeze +fstrim i386.8 ia64.8 ipcmk diff --git a/sys-utils/Makefile.am b/sys-utils/Makefile.am index a45978e3..3bcae52c 100644 --- a/sys-utils/Makefile.am +++ b/sys-utils/Makefile.am @@ -10,12 +10,12 @@ dist_man_MANS = flock.1 ipcrm.1 ipcs.1 ipcmk.1 renice.1 setsid.1 \ if LINUX bin_PROGRAMS += dmesg -sbin_PROGRAMS += ctrlaltdel fsfreeze +sbin_PROGRAMS += ctrlaltdel fsfreeze fstrim usrbin_exec_PROGRAMS += cytune setarch usrsbin_exec_PROGRAMS += ldattach tunelp rtcwake dist_man_MANS += dmesg.1 ctrlaltdel.8 cytune.8 setarch.8 \ - ldattach.8 tunelp.8 rtcwake.8 fsfreeze.8 + ldattach.8 tunelp.8 rtcwake.8 fsfreeze.8 fstrim.8 if HAVE_CPU_SET_T usrbin_exec_PROGRAMS += lscpu @@ -27,7 +27,7 @@ endif cytune_SOURCES = cytune.c cyclades.h tunelp_SOURCES = tunelp.c lp.h - +fstrim_SOURCES = fstrim.c $(top_srcdir)/lib/strutils.c if BUILD_FALLOCATE usrbin_exec_PROGRAMS += fallocate diff --git a/sys-utils/fstrim.8 b/sys-utils/fstrim.8 new file mode 100644 index 00000000..ae6ff8a1 --- /dev/null +++ b/sys-utils/fstrim.8 @@ -0,0 +1,84 @@ +.\" -*- nroff -*- +.TH FSTRIM 8 "Nov 2010" +.SH NAME +fstrim \- discard unused blocks on a mounted filesystem +.SH SYNOPSIS +.B fstrim +.RB [ \-o +.IR offset ] +.RB [ \-l +.IR length ] +.RB [ \-m +.IR minimum-extent ] +.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. + +.SH OPTIONS +The \fIoffset\fR, \fIlength\fR, and \fIminimum-free-extent\fR arguments may be +followed by binary (2^N) suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is +optional, e.g. "K" has the same meaning as "KiB") or decimal (10^N) suffixes +KB, MB, GB, PB and EB. +.IP "\fB\-h, \-\-help\fP" +Print help and exit. +.IP "\fB\-o, \-\-offset\fP \fIoffset\fP" +Byte offset in filesystem from which to begin searching for free blocks +to discard. Default value is zero, starting at the beginning of the +filesystem. +.IP "\fB\-l, \-\-length\fP \fIlength\fP" +Number of bytes after 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. Default value extends to the end +of the filesystem. +.IP "\fB\-m, \-\-minimum\fP \fIminimum-free-extent\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. Default value is zero, discard +every free block. +.IP "\fB\-v, \-\-verbose\fP" +Verbose execution. When specified +.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. + +.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). + +.SH AUTHOR +.nf +Lukas Czerner +Karel Zak +.fi +.SH SEE ALSO +.BR mount (8) +.SH AVAILABILITY +The fstrim command is part of the util-linux-ng package and is available from +ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/. diff --git a/sys-utils/fstrim.c b/sys-utils/fstrim.c new file mode 100644 index 00000000..fd83d311 --- /dev/null +++ b/sys-utils/fstrim.c @@ -0,0 +1,154 @@ +/* + * fstrim.c -- discard the part (or whole) of mounted filesystem. + * + * Copyright (C) 2010 Red Hat, Inc. All rights reserved. + * Written by Lukas Czerner + * Karel Zak + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + * + * + * This program uses FITRIM ioctl to discard parts or the whole filesystem + * online (mounted). You can specify range (start and length) to be + * discarded, or simply discard while filesystem. + */ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include + +#include "nls.h" +#include "strutils.h" + +#ifndef FITRIM +struct fstrim_range { + uint64_t start; + uint64_t len; + uint64_t minlen; +}; +#define FITRIM _IOWR('X', 121, struct fstrim_range) +#endif + +static void __attribute__((__noreturn__)) usage(FILE *out) +{ + fprintf(out, _("Usage: %s [options] \n\nOptions:\n"), + program_invocation_short_name); + + fprintf(out, _( + " -h, --help this help\n" + " -o, --offset offset in bytes to discard from\n" + " -l, --length length of bytes to discard from the offset\n" + " -m, --minimum minimum extent length to discard\n" + " -v, --verbose print number of discarded bytes\n")); + + fprintf(out, _("\nFor more information see fstrim(1).\n")); + + exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS); +} + +int main(int argc, char **argv) +{ + char *path; + int c, fd, verbose = 0; + struct fstrim_range range; + struct stat sb; + + struct option longopts[] = { + { "help", 0, 0, 'h' }, + { "offset", 1, 0, 'o' }, + { "length", 1, 0, 'l' }, + { "minimum", 1, 0, 'm' }, + { "verbose", 0, 0, 'v' }, + { NULL, 0, 0, 0 } + }; + + setlocale(LC_ALL, ""); + bindtextdomain(PACKAGE, LOCALEDIR); + textdomain(PACKAGE); + + memset(&range, 0, sizeof(range)); + range.len = ULLONG_MAX; + + while ((c = getopt_long(argc, argv, "ho:l:m:v", longopts, NULL)) != -1) { + switch(c) { + case 'h': + usage(stdout); + break; + case 'l': + if (strtosize(optarg, &range.len)) + errx(EXIT_FAILURE, + _("failed to parse length: %s"), optarg); + break; + case 'o': + if (strtosize(optarg, &range.start)) + errx(EXIT_FAILURE, + _("failed to parse offset: %s"), optarg); + break; + case 'm': + if (strtosize(optarg, &range.minlen)) + errx(EXIT_FAILURE, + _("failed to parse minimal extend length: %s"), + optarg); + break; + case 'v': + verbose = 1; + break; + default: + usage(stderr); + break; + } + } + + if (optind == argc) + errx(EXIT_FAILURE, _("no mountpoint specified.")); + + path = argv[optind++]; + + if (optind != argc) { + warnx(_("unexpected number of arguments")); + usage(stderr); + } + + if (stat(path, &sb) == -1) + err(EXIT_FAILURE, _("%s: stat failed"), path); + if (!S_ISDIR(sb.st_mode)) + errx(EXIT_FAILURE, _("%s: not a directory"), path); + + fd = open(path, O_RDONLY); + if (fd < 0) + err(EXIT_FAILURE, _("%s: open failed"), path); + + if (ioctl(fd, FITRIM, &range)) { + int errsv = errno; + close(fd); + error(EXIT_FAILURE, errsv, _("%s: FITRIM ioctl failed"), path); + } + if (verbose) + printf(_("%s: %" PRIu64 " bytes was trimmed\n"), + path, range.len); + close(fd); + return EXIT_SUCCESS; +}