diff options
Diffstat (limited to 'doc/coreutils.texi')
| -rw-r--r-- | doc/coreutils.texi | 328 |
1 files changed, 326 insertions, 2 deletions
diff --git a/doc/coreutils.texi b/doc/coreutils.texi index e29af8bec..e248af0e2 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -85,6 +85,7 @@ * nl: (coreutils)nl invocation. Number lines and write files. * nohup: (coreutils)nohup invocation. Immunize to hangups. * nproc: (coreutils)nproc invocation. Print the number of processors. +* numfmt: (coreutils)numfmt invocation. Reformat numbers. * od: (coreutils)od invocation. Dump files in octal, etc. * paste: (coreutils)paste invocation. Merge lines of files. * pathchk: (coreutils)pathchk invocation. Check file name portability. @@ -238,9 +239,12 @@ Output of entire files Formatting file contents * fmt invocation:: Reformat paragraph text +* numfmt invocation:: Reformat numbers * pr invocation:: Paginate or columnate files for printing * fold invocation:: Wrap input lines to fit in specified width +@command{numfmt}: General Options, Units + Output of parts of files * head invocation:: Output the first part of files @@ -764,8 +768,8 @@ other exit status values and a few associate different meanings with the values @samp{0} and @samp{1}. Here are some of the exceptions: @command{chroot}, @command{env}, @command{expr}, @command{nice}, -@command{nohup}, @command{printenv}, @command{sort}, @command{stdbuf}, -@command{test}, @command{timeout}, @command{tty}. +@command{nohup}, @command{numfmt}, @command{printenv}, @command{sort}, +@command{stdbuf}, @command{test}, @command{timeout}, @command{tty}. @node Backup options @@ -2122,6 +2126,7 @@ These commands reformat the contents of files. @menu * fmt invocation:: Reformat paragraph text. +* numfmt invocation:: Reformat numbers. * pr invocation:: Paginate or columnate files for printing. * fold invocation:: Wrap input lines to fit in specified width. @end menu @@ -2231,6 +2236,325 @@ leaving the code unchanged. @exitstatus +@node numfmt invocation +@section @command{numfmt}: Reformat numbers + +@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} +representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}). + +@example +numfmt [@var{option}]@dots{} [@var{number}] +@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 +specific columns, maintaining proper line padding and alignment. + +@exitstatus + +See @option{--invalid} for additional information regarding exit status. + +@subsection General options + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item --from=@var{unit} +@opindex --from +Auto-scales input numbers according to @var{unit}. See @emph{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} +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. + +@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. +@option{--invalid=@samp{abort}} explicitly specifies this default mode. +With a @var{mode} of @samp{fail}, print a warning for @emph{each} conversion +error, and exit with status 2. With a @var{mode} of @samp{warn}, exit with +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 --debug +@opindex --debug +Print (to standard error) warning messages about possible erroneous usage. + +@end table + +@subsection Possible @var{unit}s: + +The following are the possible @var{unit} options with @option{--from=UNITS} and +@option{--to=UNITS}: + +@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 +numbers, all digits of the numbers will be printed. + +@item si +Auto-scale numbers according to the @emph{International System of Units (SI)} +standard. +For input numbers, accept one of the following suffixes. +For output numbers, values larger than 1000 will be rounded, and printed with +one of the following suffixes: + +@example +@samp{K} => @math{1000^1 = 10^3} (Kilo) +@samp{M} => @math{1000^2 = 10^6} (Mega) +@samp{G} => @math{1000^3 = 10^9} (Giga) +@samp{T} => @math{1000^4 = 10^{12}} (Tera) +@samp{P} => @math{1000^5 = 10^{15}} (Peta) +@samp{E} => @math{1000^6 = 10^{18}} (Exa) +@samp{Z} => @math{1000^7 = 10^{21}} (Zetta) +@samp{Y} => @math{1000^8 = 10^{24}} (Yotta) +@end example + +@item iec +Auto-scale numbers according to the @emph{International Electronical +Commission (IEC)} standard. +For input numbers, accept one of the following suffixes. +For output numbers, values larger than 1024 will be rounded, and printed with +one of the following suffixes: + +@example +@samp{K} => @math{1024^1 = 2^{10}} (Kibi) +@samp{M} => @math{1024^2 = 2^{20}} (Mebi) +@samp{G} => @math{1024^3 = 2^{30}} (Gibi) +@samp{T} => @math{1024^4 = 2^{40}} (Tebi) +@samp{P} => @math{1024^5 = 2^{50}} (Pebi) +@samp{E} => @math{1024^6 = 2^{60}} (Exbi) +@samp{Z} => @math{1024^7 = 2^{70}} (Zebi) +@samp{Y} => @math{1024^8 = 2^{80}} (Yobi) +@end example + +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 +the @option{iec-i} option. + +@item iec-i +Auto-scale numbers according to the @emph{International Electronical +Commission (IEC)} standard. +For input numbers, accept one of the following suffixes. +For output numbers, values larger than 1024 will be rounded, and printed with +one of the following suffixes: + +@example +@samp{Ki} => @math{1024^1 = 2^{10}} (Kibi) +@samp{Mi} => @math{1024^2 = 2^{20}} (Mebi) +@samp{Gi} => @math{1024^3 = 2^{30}} (Gibi) +@samp{Ti} => @math{1024^4 = 2^{40}} (Tebi) +@samp{Pi} => @math{1024^5 = 2^{50}} (Pebi) +@samp{Ei} => @math{1024^6 = 2^{60}} (Exbi) +@samp{Zi} => @math{1024^7 = 2^{70}} (Zebi) +@samp{Yi} => @math{1024^8 = 2^{80}} (Yobi) +@end example + +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. + +@item auto +@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 +are interpreted as @emph{IEC} values. + +@end table + +@subsection Examples of using @command{numfmt} + +Converting a single number from/to @emph{human} representation: +@example +$ nunfmt --to=si 500000 +500K + +$ numfmt --to=iec 500000 +489K + +$ numfmt --to=iec-i 500000 +489Ki + +$ numfmt --from=si 1M +1000000 + +$ numfmt --from=iec 1M +1048576 + +# with '--from=auto', M=Mega, Mi=Mebi +$ numfmt --from=auto 1M +1000000 +$ numfmt --from=auto 1Mi +1048576 +@end example + +Converting from @samp{SI} to @samp{IEC} scales (e.g. when a harddisk capacity is +advertised as @samp{1TB}, while checking the drive's capacity gives lower +values): + +@example +$ numfmt --from=si --to=iec 1T +932G +@end example + + +Converting a single field from an input file / piped input (these contrived +examples are for demonstration purposes only, as both @command{ls} and +@command{df} support the @option{--human-readable} option to +output sizes in human-readable format): + +@example +# Third field (file size) will be shown in SI representation +$ ls -log | numfmt --field 3 --header --to=si | head -n4 +-rw-r--r-- 1 94K Aug 23 2011 ABOUT-NLS +-rw-r--r-- 1 3.7K Jan 7 16:15 AUTHORS +-rw-r--r-- 1 36K Jun 1 2011 COPYING +-rw-r--r-- 1 0 Jan 7 15:15 ChangeLog + +# Second field (size) will be shown in IEC representation +$ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4 +File system 1B-blocks Used Available Use% Mounted on +rootfs 132G 104741408 26554036 80% / +tmpfs 794M 7580 804960 1% /run/shm +/dev/sdb1 694G 651424756 46074696 94% /home +@end example + + +Output can be tweaked using @option{--padding} or @option{--format}: + +@example +# Pad to 10 characters, right-aligned +$ du -s * | numfmt --to=si --padding=10 + 2.5K config.log + 108 config.status + 1.7K configure + 20 configure.ac + +# Pad to 10 characters, left-aligned +$ du -s * | numfmt --to=si --padding=-10 +2.5K config.log +108 config.status +1.7K configure +20 configure.ac + +# Pad to 10 characters, left-aligned, using 'format' +$ du -s * | numfmt --to=si --format="%10f" + 2.5K config.log + 108 config.status + 1.7K configure + 20 configure.ac + +# Pad to 10 characters, left-aligned, using 'format' +$ du -s * | numfmt --to=si --padding="%-10f" +2.5K config.log +108 config.status +1.7K configure +20 configure.ac +@end example + +With locales that support grouping digits, using @option{--grouping} or +@option{--format} enables grouping. In @samp{POSIX} locale, grouping is silently +ignored: + +@example +$ LC_ALL=C numfmt --from=iec --grouping 2G +2147483648 + +$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G +2,147,483,648 + +$ LC_ALL=ta_IN numfmt --from=iec --grouping 2G +2,14,74,83,648 + +$ LC_ALL=C ./src/numfmt --from=iec --format="==%'15f==" 2G +== 2147483648== + +$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'15f==" 2G +== 2,147,483,648== + +$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'-15f==" 2G +==2,147,483,648 == + +$ LC_ALL=ta_IN ./src/numfmt --from=iec --format="==%'15f==" 2G +== 2,14,74,83,648== +@end example @node pr invocation @section @command{pr}: Paginate or columnate files for printing |