@pindex numfmt
@command{numfmt} reads numbers in various representations and reformats them
-as requested. The most common usage is converting numbers to/from @emph{human}
+as requested. The most common usage is converting numbers to/from @emph{human}
representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}).
@example
@end example
@command{numfmt} converts each @var{number} on the command-line according to the
-specified options (see below). If no @var{number}s are given, it reads numbers
-from standard input. @command{numfmt} can optionally extract numbers from
+specified options (see below). If no @var{number}s are given, it reads numbers
+from standard input. @command{numfmt} can optionally extract numbers from
specific columns, maintaining proper line padding and alignment.
@exitstatus
@table @samp
+@item --debug
+@opindex --debug
+Print (to standard error) warning messages about possible erroneous usage.
+
+@item -d @var{d}
+@itemx --delimiter=@var{d}
+@opindex -d
+@opindex --delimiter
+Use the character @var{d} as input field separator (default: whitespace).
+@emph{Note}: Using non-default delimiter turns off automatic padding.
+
+@item --field=@var{n}
+@opindex --field
+Convert the number in input field @var{n} (default: 1).
+
+@item --format=@var{format}
+@opindex --format
+Use printf-style floating FORMAT string. The @var{format} string must contain
+one @samp{%f} directive, optionally with @samp{'}, @samp{-}, or width
+modifiers. The @samp{'} modifier will enable @option{--grouping}, the @samp{-}
+modifier will enable left-aligned @option{--padding} and the width modifier will
+enable right-aligned @option{--padding}.
+
@item --from=@var{unit}
@opindex --from
-Auto-scales input numbers according to @var{unit}. See @emph{Units} below.
+Auto-scales input numbers according to @var{unit}. See UNITS below.
The default is no scaling, meaning suffixes (e.g. @samp{M}, @samp{G}) will
trigger an error.
@item --from-unit=@var{n}
@opindex --from-unit
-Specify the input unit size (instead of the default 1). Use this option when the
-input numbers represent other units (e.g. if the input number @samp{10}
+Specify the input unit size (instead of the default 1). Use this option when
+the input numbers represent other units (e.g. if the input number @samp{10}
represents 10 units of 512 bytes, use @samp{--from=unit=512}).
-@item --to=@var{unit}
-@opindex --to
-Auto-scales output numbers according to @var{unit}. See @emph{Units} below.
-The default is no scaling, meaning all the digits of the number are printed.
-
-@item --to-unit=@var{n}
-@opindex --to-unit
-Specify the output unit size (instead of the default 1). Use this option when
-the output numbers represent other units (e.g. to represent @samp{4,000,000}
-bytes in blocks of 1KB, use @samp{--to=si --to=units=1000}).
-
-@item --round=@var{method}
-@opindex --round
-@opindex --round=up
-@opindex --round=down
-@opindex --round=from-zero
-@opindex --round=towards-zero
-@opindex --round=nearest
-When converting number representations, round the number according to
-@var{method}, which can be @samp{up}, @samp{down},
-@samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}.
-
-@item --suffix=@var{suffix}
-@opindex --suffix
-Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in
-input numbers.
-
-@item --padding=@var{n}
-@opindex --padding
-Pad the output numbers to @var{n} characters, by adding spaces. If @var{n} is
-a positive number, numbers will be right-aligned. If @var{n} is a negative
-number, numbers will be left-aligned. By default, numbers are automatically
-aligned based on the input line's width (only with the default delimiter).
-
@item --grouping
@opindex --grouping
Group digits in output numbers according to the current locale's grouping rules
(e.g @emph{Thousands Separator} character, commonly @samp{.} (dot) or @samp{,}
-comma). This option has no effect in @samp{POSIX/C} locale.
+comma). This option has no effect in @samp{POSIX/C} locale.
@item --header[=@var{n}]
@opindex --header
@opindex --header=N
Print the first @var{n} (default: 1) lines without any conversion.
-@item --field=@var{n}
-@opindex --field
-Convert the number in input field @var{n} (default: 1).
-
-@item --format=@var{format}
-@opindex --format
-Use printf-style floating FORMAT string. The @var{format} string must contain
-one @samp{%f} directive, optionally with @samp{'}, @samp{-}, or width
-modifiers. @samp{'} modified will enable @option{--grouping}. @samp{-} modifier
-will enable left-aligned @option{--padding}. Width modifier will enable
-right-aligned @option{--padding}.
-
@item --invalid=@var{mode}
@opindex --invalid
The default action on input errors is to exit immediately with status code 2.
status 0, even in the presence of conversion errors, and with a @var{mode} of
@samp{ignore} do not even print diagnostics.
-@item -d @var{d}
-@itemx --delimiter=@var{d}
-@opindex -d
-@opindex --delimiter
-Use the character @var{d} as input field separator (default: whitespace).
-@emph{Note}: Using non-default delimiter turns off automatic padding.
+@item --padding=@var{n}
+@opindex --padding
+Pad the output numbers to @var{n} characters, by adding spaces. If @var{n} is
+a positive number, numbers will be right-aligned. If @var{n} is a negative
+number, numbers will be left-aligned. By default, numbers are automatically
+aligned based on the input line's width (only with the default delimiter).
-@item --debug
-@opindex --debug
-Print (to standard error) warning messages about possible erroneous usage.
+@item --round=@var{method}
+@opindex --round
+@opindex --round=up
+@opindex --round=down
+@opindex --round=from-zero
+@opindex --round=towards-zero
+@opindex --round=nearest
+When converting number representations, round the number according to
+@var{method}, which can be @samp{up}, @samp{down},
+@samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}.
+
+@item --suffix=@var{suffix}
+@opindex --suffix
+Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in
+input numbers.
+
+@item --to=@var{unit}
+@opindex --to
+Auto-scales output numbers according to @var{unit}. See @emph{Units} below.
+The default is no scaling, meaning all the digits of the number are printed.
+
+@item --to-unit=@var{n}
+@opindex --to-unit
+Specify the output unit size (instead of the default 1). Use this option when
+the output numbers represent other units (e.g. to represent @samp{4,000,000}
+bytes in blocks of 1KB, use @samp{--to=si --to=units=1000}).
@end table
@table @var
@item none
-No scaling is performed. For input numbers, no suffixes are accepted, and any
-trailing characters following the number will trigger an error. For output
+No scaling is performed. For input numbers, no suffixes are accepted, and any
+trailing characters following the number will trigger an error. For output
numbers, all digits of the numbers will be printed.
@item si
The @option{iec} option uses a single letter suffix (e.g. @samp{G}), which is
not fully standard, as the @emph{iec} standard recommends a two-letter symbol
-(e.g @samp{Gi}) - but in practice, this method common. Compare with
+(e.g @samp{Gi}) - but in practice, this method common. Compare with
the @option{iec-i} option.
@item iec-i
The @option{iec-i} option uses a two-letter suffix symbol (e.g. @samp{Gi}),
as the @emph{iec} standard recommends, but this is not always common in
-practice. Compare with the @option{iec} option.
+practice. Compare with the @option{iec} option.
@item auto
-@samp{auto} can only be used with @option{--from}. With this method, numbers
+@samp{auto} can only be used with @option{--from}. With this method, numbers
with @samp{K},@samp{M},@samp{G},@samp{T},@samp{P},@samp{E},@samp{Z},@samp{Y}
suffixes are interpreted as @emph{SI} values, and numbers with @samp{Ki},
@samp{Mi},@samp{Gi},@samp{Ti},@samp{Pi},@samp{Ei},@samp{Zi},@samp{Yi} suffixes
@end example
With locales that support grouping digits, using @option{--grouping} or
-@option{--format} enables grouping. In @samp{POSIX} locale, grouping is silently
-ignored:
+@option{--format} enables grouping. In @samp{POSIX} locale, grouping is
+silently ignored:
@example
$ LC_ALL=C numfmt --from=iec --grouping 2G
else
{
printf (_("\
-Usage: %s [OPTIONS] [NUMBER]\n\
+Usage: %s [OPTION]... [NUMBER]...\n\
"), program_name);
fputs (_("\
-Reformat NUMBER(s) from stdin or command arguments.\n\
+Reformat NUMBER(s), or the numbers from standard input if none are specified.\n\
"), stdout);
emit_mandatory_arg_note ();
fputs (_("\
- --from=UNIT auto-scale input numbers to UNITs. Default is 'none'.\n\
- See UNIT below.\n\
- --from-unit=N specify the input unit size (instead of the default 1).\n\
- --to=UNIT auto-scale output numbers to UNITs.\n\
- See UNIT below.\n\
- --to-unit=N the output unit size (instead of the default 1).\n\
- --round=METHOD the rounding method to use when scaling. METHOD can be:\n\
- up, down, from-zero (default), towards-zero, nearest\n\
- --suffix=SUFFIX add SUFFIX to output numbers, and accept optional SUFFIX\n\
- in input numbers.\n\
- --padding=N pad the output to N characters.\n\
- Positive N will right-aligned. Negative N will left-align.\n\
- Note: if the output is wider than N, padding is ignored.\n\
- Default is to automatically pad if whitespace is found.\n\
- --grouping group digits together (e.g. 1,000,000).\n\
- Uses the locale-defined grouping (i.e. have no effect\n\
- in C/POSIX locales).\n\
- --header[=N] print (without converting) the first N header lines.\n\
- N defaults to 1 if not specified.\n\
- --field N replace the number in input field N (default is 1)\n\
- -d, --delimiter=X use X instead of whitespace for field delimiter\n\
- --format=FORMAT use printf style floating-point FORMAT.\n\
- See FORMAT below for details.\n\
- --invalid=MODE failure mode for invalid numbers: MODE can be:\n\
- abort (the default), fail, warn, ignore.\n\
- --debug print warnings about invalid input.\n\
- \n\
+ --debug print warnings about invalid input\n\
"), stdout);
+ fputs (_("\
+ -d, --delimiter=X use X instead of whitespace for field delimiter\n\
+"), stdout);
+ fputs (_("\
+ --field=N replace the number in input field N (default is 1)\n\
+"), stdout);
+ fputs (_("\
+ --format=FORMAT use printf style floating-point FORMAT;\n\
+ see FORMAT below for details\n\
+"), stdout);
+ fputs (_("\
+ --from=UNIT auto-scale input numbers to UNITs; default is 'none';\n\
+ see UNIT below\n\
+"), stdout);
+ fputs (_("\
+ --from-unit=N specify the input unit size (instead of the default 1)\n\
+"), stdout);
+ fputs (_("\
+ --grouping use locale-defined grouping of digits, e.g. 1,000,000\n\
+ (which means it has no effect in the C/POSIX locale)\n\
+"), stdout);
+ fputs (_("\
+ --header[=N] print (without converting) the first N header lines;\n\
+ N defaults to 1 if not specified\n\
+"), stdout);
+ fputs (_("\
+ --invalid=MODE failure mode for invalid numbers: MODE can be:\n\
+ abort (default), fail, warn, ignore\n\
+"), stdout);
+ fputs (_("\
+ --padding=N pad the output to N characters; positive N will\n\
+ right-align; negative N will left-align;\n\
+ padding is ignored if the output is wider than N;\n\
+ the default is to automatically pad if a whitespace\n\
+ is found\n\
+"), stdout);
+ fputs (_("\
+ --round=METHOD use METHOD for rounding when scaling; METHOD can be:\n\
+ up, down, from-zero (default), towards-zero, nearest\n\
+"), stdout);
+ fputs (_("\
+ --suffix=SUFFIX add SUFFIX to output numbers, and accept optional\n\
+ SUFFIX in input numbers\n\
+"), stdout);
+ fputs (_("\
+ --to=UNIT auto-scale output numbers to UNITs; see UNIT below\n\
+"), stdout);
+ fputs (_("\
+ --to-unit=N the output unit size (instead of the default 1)\n\
+"), stdout);
+
fputs (HELP_OPTION_DESCRIPTION, stdout);
fputs (VERSION_OPTION_DESCRIPTION, stdout);
-
fputs (_("\
\n\
-UNIT options:\n\
- none No auto-scaling is done. Suffixes will trigger an error.\n\
- auto Accept optional single-letter/two-letter suffix:\n\
- 1K = 1000\n\
- 1Ki = 1024\n\
- 1M = 1000000\n\
- 1Mi = 1048576\n\
- si Accept optional single letter suffix:\n\
- 1K = 1000\n\
- 1M = 1000000\n\
- ...\n\
- iec Accept optional single letter suffix:\n\
- 1K = 1024\n\
- 1M = 1048576\n\
- ...\n\
- iec-i Accept optional two-letter suffix:\n\
- 1Ki = 1024\n\
- 1Mi = 1048576\n\
- ...\n\
-\n\
+UNIT options:\n"), stdout);
+ fputs (_("\
+ none no auto-scaling is done; suffixes will trigger an error\n\
"), stdout);
-
fputs (_("\
-\n\
+ auto accept optional single-letter/two-letter suffix:\n\
+ 1K = 1000\n\
+ 1Ki = 1024\n\
+ 1M = 1000000\n\
+ 1Mi = 1048576\n"), stdout);
+ fputs (_("\
+ si accept optional single letter suffix:\n\
+ 1K = 1000\n\
+ 1M = 1000000\n\
+ ...\n"), stdout);
+ fputs (_("\
+ iec accept optional single letter suffix:\n\
+ 1K = 1024\n\
+ 1M = 1048576\n\
+ ...\n"), stdout);
+ fputs (_("\
+ iec-i accept optional two-letter suffix:\n\
+ 1Ki = 1024\n\
+ 1Mi = 1048576\n\
+ ...\n"), stdout);
+
+ fputs (_("\n\
FORMAT must be suitable for printing one floating-point argument '%f'.\n\
Optional quote (%'f) will enable --grouping (if supported by current locale).\n\
Optional width value (%10f) will pad output. Optional negative width values\n\
(%-10f) will left-pad output.\n\
-\n\
"), stdout);
- printf (_("\
-\n\
+ printf (_("\n\
Exit status is 0 if all input numbers were successfully converted.\n\
By default, %s will stop at the first conversion error with exit status 2.\n\
With --invalid='fail' a warning is printed for each conversion error\n\
and the exit status is 2. With --invalid='warn' each conversion error is\n\
diagnosed, but the exit status is 0. With --invalid='ignore' conversion\n\
errors are not diagnosed and the exit status is 0.\n\
-\n\
"), program_name);
-
-
- printf (_("\
-\n\
+ printf (_("\n\
Examples:\n\
$ %s --to=si 1000\n\
-> \"1.0K\"\n\
$ df | %s --header --field 2 --to=si\n\
$ ls -l | %s --header --field 5 --to=iec\n\
$ ls -lh | %s --header --field 5 --from=iec --padding=10\n\
- $ ls -lh | %s --header --field 5 --from=iec --format %%10f\n\
-"),
+ $ ls -lh | %s --header --field 5 --from=iec --format %%10f\n"),
program_name, program_name, program_name,
program_name, program_name, program_name,
program_name, program_name, program_name);
projects / platform / upstream / coreutils.git / commitdiff