From bac650ff56f95cc81d1ce6571ef78cbb065b6f2e Mon Sep 17 00:00:00 2001 From: Alexandre Ioffe Date: Wed, 3 Jan 2024 19:34:40 -0800 Subject: [PATCH] LU-17370 utils: simplify lfs-mirror-extend help text Add list of lfs setstripe command line options to help text of lfs mirror extend. Simplify syntax of lfs mirror extend help text. Update corresponding lfs-mirror-extend man page. On man pages make left side adjustment and disable hyphenation: '.nh', '.ad l' to prevent hyphenation of keywords Signed-off-by: Alexandre Ioffe Test-Parameters: trivial Change-Id: I6cffcdb9651062e169f53868827646b876a82cb5 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/53719 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Andreas Dilger Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin --- lustre/doc/lfs-mirror-extend.1 | 57 ++++++++++++++--------------- lustre/utils/lfs.c | 81 ++++++++++++++++++------------------------ 2 files changed, 63 insertions(+), 75 deletions(-) diff --git a/lustre/doc/lfs-mirror-extend.1 b/lustre/doc/lfs-mirror-extend.1 index c646a04..aa08df7 100644 --- a/lustre/doc/lfs-mirror-extend.1 +++ b/lustre/doc/lfs-mirror-extend.1 @@ -2,41 +2,42 @@ .SH NAME lfs-mirror-extend \- add mirror(s) to an existing file .SH SYNOPSIS +.nh +.ad l .B lfs mirror extend [\fB\-\-no\-verify\fR] -<\fB\-\-mirror\-count\fR|\fB\-N\fR[\fImirror_count\fR]> -<\fB\-\-bandwidth\-limit=\fR|\fB\-W\fR[\fIbandwidth_limit\fR]> -[\fB\-\-stats\fR] -<\fB\-\-stats\-interval\fR=\fIinterval_in_sec\fR> -[\fIsetstripe_options\fR|\fB\-f\fR <\fIvictim_file\fR>] ... -<\fIfilename\fR> +\fB\-\-mirror\-count\fR|\fB\-N\fR[\fIMIRROR_COUNT\fR] +[\fB\-\-bandwidth\-limit\fR|\fB\-W\fR \fIBANDWIDTH\fR] +[\fB\-\-stats\fR|\fB\-\-stats\-interval\fR=\fISTATS_INTERVAL\fR] +[\fISETSTRIPE_OPTIONS\fR|\fB\-f\fR \fIVICTIM_FILE\fR] +\fIFILENAME\fR ... .SH DESCRIPTION This command adds mirror(s) to an existing file specified by the path name -\fIfilename\fR. +\fIFILENAME\fR. .br -The file \fIfilename\fR can already be a mirrored file, or just a regular +The file \fIFILENAME\fR can already be a mirrored file, or just a regular non-mirrored file. If it's a non-mirrored file, then the command will convert it to a mirrored file. .br The \fB\-\-mirror\-count\fR|\fB\-N\fR option is required and indicates how many mirrors that have the same layout will be added. It can be repeated multiple -times to separate mirrors that have different layouts. The \fImirror_count\fR +times to separate mirrors that have different layouts. The \fIMIRROR_COUNT\fR argument is optional and defaults to 1 if it's not specified; if specified, it must follow the option without a space. .br -The \fIsetstripe_options\fR specify the specific layout for the mirror. It can +The \fISETSTRIPE_OPTIONS\fR specify the specific layout for the mirror. It can be a plain layout with specific striping pattern or a composite layout like Progressive File Layout (PFL) (see \fBlfs-setstripe\fR(1)). -If \fIsetstripe_options\fR are not specified, +If \fISETSTRIPE_OPTIONS\fR are not specified, then the stripe options inherited from the previous component will be used. -If \fIvictim_file\fR exists, then the +If \fIVICTIM_FILE\fR exists, then the command will merge the layout from that file as a mirror added to the mirrored file. After the command is finished, the victim file will be -removed. The \fIsetstripe_options\fR cannot be specified with -\fB\-f\fR <\fIvictim_file\fR> option in one command line. +removed. The \fISETSTRIPE_OPTIONS\fR cannot be specified with +\fB\-f\fR \fIVICTIM_FILE\fR option in one command line. .br -If \fIvictim_file\fR is specified, the utility will verify that the file contents -from \fIvictim_file\fR are the same as \fIfilename\fR. Otherwise the command +If \fIVICTIM_FILE\fR is specified, the utility will verify that the file contents +from \fIVICTIM_FILE\fR are the same as \fIFILENAME\fR. Otherwise the command will return failure. However, option \fB\-\-no\-verify\fR can be used to override this verification. The option can save siginificant time on file comparison if the file size is large, but use it only when the file contents @@ -45,22 +46,22 @@ are known to be the same. If no option is specified, then the command will return an error. .SH OPTIONS .TP -.BR \-\-mirror\-count\fR|\fB\-N\fR[\fImirror_count\fR] +.BR \-\-mirror\-count\fR|\fB\-N\fR[\fIMIRROR_COUNT\fR] The number of mirrors that have the same layout to be added. The option can be repeated multiple times to separate mirrors that have different layouts. The -\fImirror_count\fR argument is optional and defaults to 1 if it's not specified; +\fIMIRROR_COUNT\fR argument is optional and defaults to 1 if it's not specified; if specified, it must follow the option without a space. .TP -.I setstripe_options +.I SETSTRIPE_OPTIONS The layout of one mirror. The options are the same as those for \fBlfs-setstripe\fR(1) command. -If \fIsetstripe_options\fR are not specified, then the stripe options inherited +If \fISETSTRIPE_OPTIONS\fR are not specified, then the stripe options inherited from the previous component will be used. This option cannot be specified with -\fB\-f\fR <\fIvictim_file\fR> option. +\fB\-f\fR \fIVICTIM_FILE\fR option. .TP -.BR \-f\fR\ <\fIvictim_file\fR> -The layout of \fIvictim_file\fR will be merged as a mirror added to the -mirrored file. This option cannot be specified with \fIsetstripe_options\fR +.BR \-f\fR\ \fIVICTIM_FILE\fR +The layout of \fIVICTIM_FILE\fR will be merged as a mirror added to the +mirrored file. This option cannot be specified with \fISETSTRIPE_OPTIONS\fR option. .TP .BR \-\-no\-verify @@ -70,12 +71,12 @@ the victim file(s) contains the same data as the original mirrored file. .BR \-\-stats This option enables progress updates every 5 seconds, in YAML format. .TP -.BR \-\-stats-interval=\fIstats_interval -This option enables progress updates every \fIstats_interval\fR seconds, in YAML format. +.BR \-\-stats-interval=\fISTATS_INTERVAL +This option enables progress updates every \fISTATS_INTERVAL\fR seconds, in YAML format. .TP -.BR \-\-bandwidth\-limit\fR|\fB\-W\fR\fIbandwidth_limit\fR +.BR \-\-bandwidth\-limit\fR|\fB\-W\fR\fIBANDWIDTH\fR This option enables throttling so that mirror extending writes no more than -\fIbandwidth_limit\fR bytes a second. An optional suffix can be used to +\fIBANDWIDTH\fR bytes a second. An optional suffix can be used to specify the units in .BR K ilobytes, .BR M egabytes diff --git a/lustre/utils/lfs.c b/lustre/utils/lfs.c index 5a78328..6bf2621 100644 --- a/lustre/utils/lfs.c +++ b/lustre/utils/lfs.c @@ -194,51 +194,36 @@ static inline int lfs_mirror_delete(int argc, char **argv) return lfs_setstripe_internal(argc, argv, SO_MIRROR_DELETE); } +#define SSM_SETSTRIPE_OPT \ + "[--component-add|--component-del|--delete|-d]\n" \ + "\t\t[--comp-set --comp-id|-I COMP_ID|--comp-flags=COMP_FLAGS]\n" \ + "\t\t[--component-end|-E END_OFFSET]\n" \ + "\t\t[--copy=SOURCE_LAYOUT_FILE]|--yaml|-y YAML_TEMPLATE_FILE]\n" \ + "\t\t[--extension-size|--ext-size|-z EXT_SIZE]\n" \ + "\t\t[--help|-h]\n" \ + "\t\t[--foreign=FOREIGN_TYPE --xattr|-x LAYOUT]\n" \ + "\t\t[--layout|-L PATTERN] [--mode FILE_MODE]\n" \ + "\t\t[--mirror-count|-N[MIRROR_COUNT]]\n" \ + "\t\t[--ost|-o OST_INDEX[,OST_INDEX,...]]\n" \ + "\t\t[--overstripe-count|-C STRIPE_COUNT]\n" \ + "\t\t[--pool|-p POOL_NAME]\n" \ + "\t\t[--stripe-count|-c STRIPE_COUNT]\n" \ + "\t\t[--stripe-index|-i START_OST_IDX]\n" \ + "\t\t[--stripe-size|-S STRIPE_SIZE]" + /* Setstripe and migrate share mostly the same parameters */ -#define SSM_CMD_COMMON(cmd) \ - "usage: "cmd" [--component-end|-E COMP_END]\n" \ - " [--copy=LUSTRE_SRC]\n" \ - " [--extension-size|--ext-size|-z SIZE]\n" \ - " [--help|-h] [--layout|-L PATTERN]\n" \ - " [--layout|-L PATTERN]\n" \ - " [--mirror-count|-N[MIRROR_COUNT]]\n" \ - " [--ost|-o OST_INDICES]\n" \ - " [--overstripe-count|-C STRIPE_COUNT]\n" \ - " [--pool|-p POOL_NAME]\n" \ - " [--stripe-count|-c STRIPE_COUNT]\n" \ - " [--stripe-index|-i START_OST_IDX]\n" \ - " [--stripe-size|-S STRIPE_SIZE]\n" \ - " [--yaml|-y YAML_TEMPLATE_FILE]\n" - -/* XXX: A temporary solution for transition to help text update */ -#define SSM_CMD_COMMON_1(cmd) \ - "usage: "cmd" [--component-add|--component-del|--delete|-d]\n" \ - " [--comp-set --comp-id|-I COMP_ID|--comp-flags=COMP_FLAGS]\n" \ - " [--component-end|-E END_OFFSET]\n" \ - " [--copy=SOURCE_LAYOUT_FILE]|--yaml|-y YAML_TEMPLATE_FILE]\n" \ - " [--extension-size|--ext-size|-z EXT_SIZE]\n" \ - " [--help|-h]\n" \ - " [--foreign=FOREIGN_TYPE --xattr|-x LAYOUT]\n" \ - " [--layout|-L PATTERN] [--mode FILE_MODE]\n" \ - " [--mirror-count|-N[MIRROR_COUNT]]\n" \ - " [--ost|-o OST_INDEX[,OST_INDEX,...]]\n" \ - " [--overstripe-count|-C STRIPE_COUNT]\n" \ - " [--pool|-p POOL_NAME]\n" \ - " [--stripe-count|-c STRIPE_COUNT]\n" \ - " [--stripe-index|-i START_OST_IDX]\n" \ - " [--stripe-size|-S STRIPE_SIZE]\n" \ - " FILENAME|DIRECTORY\n" - -#define MIRROR_EXTEND_USAGE \ - " {--mirror-count|-N[MIRROR_COUNT]}\n" \ - " [SETSTRIPE_OPTIONS|-f|--file VICTIM_FILE]\n" \ - " [--no-verify]\n" +#define SSM_CMD_COMMON(cmd) \ + "Usage: " cmd \ + " " SSM_SETSTRIPE_OPT "\n" + +#define SETSTRIPE_USAGE \ + SSM_CMD_COMMON("setstripe ") \ + "\t\tFILENAME|DIRECTORY\n" #define MIGRATE_USAGE \ SSM_CMD_COMMON("migrate ") \ - " [--block|-b] [--non-block|-n]\n" \ - " [--non-direct|-D] [--verbose|-v]\n" \ - " FILENAME\n" + "\t\t[--block|-b] [--non-block|-n]\n" \ + "\t\t[--non-direct|-D] [--verbose|-v] FILENAME\n" \ #define SETDIRSTRIPE_USAGE \ " [--mdt-count|-c stripe_count>\n" \ @@ -267,11 +252,13 @@ command_t mirror_cmdlist[] = { }, { .pc_name = "extend", .pc_func = lfs_mirror_extend, .pc_help = "Extend a mirrored file.\n" - "usage: lfs mirror extend " - "{--mirror-count|-N[MIRROR_COUNT]} [--no-verify]|\n" - "\t\t--stats|--stats-interval=|\n" - "\t\t--W |--bandwidth-limit=\n" - "\t\t[SETSTRIPE_OPTIONS|-f VICTIM_FILE] ... FILENAME ...\n" }, + "Usage: lfs mirror extend " + "--mirror-count|-N[MIRROR_COUNT] [--no-verify]|\n" + "\t\t[--stats|--stats-interval=STATS_INTERVAL]|\n" + "\t\t[--bandwidth-limit|--W BANDWIDTH]\n" + "\t\t[[-f VICTIM_FILE] |\n" + "\t\t" SSM_SETSTRIPE_OPT "]" + " FILENAME ...\n" }, { .pc_name = "split", .pc_func = lfs_mirror_split, .pc_help = "Split a mirrored file.\n" "usage: lfs mirror split {--mirror-id MIRROR_ID |\n" @@ -332,7 +319,7 @@ command_t cmdlist[] = { {"setstripe", lfs_setstripe, 0, "Create a file with specified striping/composite layout, or\n" "set the default layout on an existing directory.\n" - SSM_CMD_COMMON_1("setstripe")}, + SETSTRIPE_USAGE}, {"getstripe", lfs_getstripe, 0, "List the layout pattern for a given file or files in a\n" "directory or recursively for all files in a directory tree.\n" -- 1.8.3.1