coreutils: numfmt invocation
1
1 26.2 ‘numfmt’: Reformat numbers
1 ===============================
1
1 ‘numfmt’ reads numbers in various representations and reformats them as
1 requested. The most common usage is converting numbers to/from _human_
1 representation (e.g. ‘4G’ ↦ ‘4,000,000,000’).
1
1 numfmt [OPTION]... [NUMBER]
1
1 ‘numfmt’ converts each NUMBER on the command-line according to the
1 specified options (see below). If no NUMBERs are given, it reads
1 numbers from standard input. ‘numfmt’ can optionally extract numbers
1 from specific columns, maintaining proper line padding and alignment.
1
1 An exit status of zero indicates success, and a nonzero value
1 indicates failure.
1
1 See ‘--invalid’ for additional information regarding exit status.
1
1 26.2.1 General options
1 ----------------------
1
11 The program accepts the following options. Also see ⇒Common
options.
1
1 ‘--debug’
1 Print (to standard error) warning messages about possible erroneous
1 usage.
1
1 ‘-d D’
1 ‘--delimiter=D’
1 Use the character D as input field separator (default: whitespace).
1 _Note_: Using non-default delimiter turns off automatic padding.
1
1 ‘--field=FIELDS’
1 Convert the number in input field FIELDS (default: 1). FIELDS
1 supports ‘cut’ style field ranges:
1
1 N N'th field, counted from 1
1 N- from N'th field, to end of line
1 N-M from N'th to M'th field (inclusive)
1 -M from first to M'th field (inclusive)
1 - all fields
1
1 ‘--format=FORMAT’
1 Use printf-style floating FORMAT string. The FORMAT string must
1 contain one ‘%f’ directive, optionally with ‘'’, ‘-’, ‘0’, width or
1 precision modifiers. The ‘'’ modifier will enable ‘--grouping’,
1 the ‘-’ modifier will enable left-aligned ‘--padding’ and the width
1 modifier will enable right-aligned ‘--padding’. The ‘0’ width
1 modifier (without the ‘-’ modifier) will generate leading zeros on
1 the number, up to the specified width. A precision specification
1 like ‘%.1f’ will override the precision determined from the input
1 data or set due to ‘--to’ option auto scaling.
1
1 ‘--from=UNIT’
1 Auto-scales input numbers according to UNIT. See UNITS below. The
1 default is no scaling, meaning suffixes (e.g. ‘M’, ‘G’) will
1 trigger an error.
1
1 ‘--from-unit=N’
1 Specify the input unit size (instead of the default 1). Use this
1 option when the input numbers represent other units (e.g. if the
1 input number ‘10’ represents 10 units of 512 bytes, use
1 ‘--from-unit=512’). Suffixes are handled as with ‘--from=auto’.
1
1 ‘--grouping’
1 Group digits in output numbers according to the current locale’s
1 grouping rules (e.g _Thousands Separator_ character, commonly ‘.’
1 (dot) or ‘,’ comma). This option has no effect in ‘POSIX/C’
1 locale.
1
1 ‘--header[=N]’
1 Print the first N (default: 1) lines without any conversion.
1
1 ‘--invalid=MODE’
1 The default action on input errors is to exit immediately with
1 status code 2. ‘--invalid=‘abort’’ explicitly specifies this
1 default mode. With a MODE of ‘fail’, print a warning for _each_
1 conversion error, and exit with status 2. With a MODE of ‘warn’,
1 exit with status 0, even in the presence of conversion errors, and
1 with a MODE of ‘ignore’ do not even print diagnostics.
1
1 ‘--padding=N’
1 Pad the output numbers to N characters, by adding spaces. If N is
1 a positive number, numbers will be right-aligned. If N is a
1 negative number, numbers will be left-aligned. By default, numbers
1 are automatically aligned based on the input line’s width (only
1 with the default delimiter).
1
1 ‘--round=METHOD’
1 When converting number representations, round the number according
1 to METHOD, which can be ‘up’, ‘down’, ‘from-zero’ (the default),
1 ‘towards-zero’, ‘nearest’.
1
1 ‘--suffix=SUFFIX’
1 Add ‘SUFFIX’ to the output numbers, and accept optional ‘SUFFIX’ in
1 input numbers.
1
1 ‘--to=UNIT’
1 Auto-scales output numbers according to UNIT. See _Units_ below.
1 The default is no scaling, meaning all the digits of the number are
1 printed.
1
1 ‘--to-unit=N’
1 Specify the output unit size (instead of the default 1). Use this
1 option when the output numbers represent other units (e.g. to
1 represent ‘4,000,000’ bytes in blocks of 1KB, use ‘--to=si
1 --to-unit=1000’). Suffixes are handled as with ‘--from=auto’.
1
1 ‘-z’
1 ‘--zero-terminated’
1 Delimit items with a zero byte rather than a newline (ASCII LF).
1 I.e., treat input as items separated by ASCII NUL and terminate
1 output items with ASCII NUL. This option can be useful in
1 conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
1 do the same in order to reliably handle arbitrary file names (even
1 those containing blanks or other special characters). Note with
1 ‘-z’ the newline character is treated as a field separator.
1
1 26.2.2 Possible UNITs:
1 ----------------------
1
1 The following are the possible UNIT options with ‘--from=UNITS’ and
1 ‘--to=UNITS’:
1
1 NONE
1 No scaling is performed. For input numbers, no suffixes are
1 accepted, and any trailing characters following the number will
1 trigger an error. For output numbers, all digits of the numbers
1 will be printed.
1
1 SI
1 Auto-scale numbers according to the _International System of Units
1 (SI)_ standard. For input numbers, accept one of the following
1 suffixes. For output numbers, values larger than 1000 will be
1 rounded, and printed with one of the following suffixes:
1
1 ‘K’ => 1000^1 = 10^3 (Kilo)
1 ‘M’ => 1000^2 = 10^6 (Mega)
1 ‘G’ => 1000^3 = 10^9 (Giga)
1 ‘T’ => 1000^4 = 10^{12} (Tera)
1 ‘P’ => 1000^5 = 10^{15} (Peta)
1 ‘E’ => 1000^6 = 10^{18} (Exa)
1 ‘Z’ => 1000^7 = 10^{21} (Zetta)
1 ‘Y’ => 1000^8 = 10^{24} (Yotta)
1
1 IEC
1 Auto-scale numbers according to the _International Electrotechnical
1 Commission (IEC)_ standard. For input numbers, accept one of the
1 following suffixes. For output numbers, values larger than 1024
1 will be rounded, and printed with one of the following suffixes:
1
1 ‘K’ => 1024^1 = 2^{10} (Kibi)
1 ‘M’ => 1024^2 = 2^{20} (Mebi)
1 ‘G’ => 1024^3 = 2^{30} (Gibi)
1 ‘T’ => 1024^4 = 2^{40} (Tebi)
1 ‘P’ => 1024^5 = 2^{50} (Pebi)
1 ‘E’ => 1024^6 = 2^{60} (Exbi)
1 ‘Z’ => 1024^7 = 2^{70} (Zebi)
1 ‘Y’ => 1024^8 = 2^{80} (Yobi)
1
1 The ‘iec’ option uses a single letter suffix (e.g. ‘G’), which is
1 not fully standard, as the _iec_ standard recommends a two-letter
1 symbol (e.g ‘Gi’) - but in practice, this method common. Compare
1 with the ‘iec-i’ option.
1
1 IEC-I
1 Auto-scale numbers according to the _International Electrotechnical
1 Commission (IEC)_ standard. For input numbers, accept one of the
1 following suffixes. For output numbers, values larger than 1024
1 will be rounded, and printed with one of the following suffixes:
1
1 ‘Ki’ => 1024^1 = 2^{10} (Kibi)
1 ‘Mi’ => 1024^2 = 2^{20} (Mebi)
1 ‘Gi’ => 1024^3 = 2^{30} (Gibi)
1 ‘Ti’ => 1024^4 = 2^{40} (Tebi)
1 ‘Pi’ => 1024^5 = 2^{50} (Pebi)
1 ‘Ei’ => 1024^6 = 2^{60} (Exbi)
1 ‘Zi’ => 1024^7 = 2^{70} (Zebi)
1 ‘Yi’ => 1024^8 = 2^{80} (Yobi)
1
1 The ‘iec-i’ option uses a two-letter suffix symbol (e.g. ‘Gi’), as
1 the _iec_ standard recommends, but this is not always common in
1 practice. Compare with the ‘iec’ option.
1
1 AUTO
1 ‘auto’ can only be used with ‘--from’. With this method, numbers
1 with ‘K’,‘M’,‘G’,‘T’,‘P’,‘E’,‘Z’,‘Y’ suffixes are interpreted as
1 _SI_ values, and numbers with ‘Ki’,
1 ‘Mi’,‘Gi’,‘Ti’,‘Pi’,‘Ei’,‘Zi’,‘Yi’ suffixes are interpreted as
1 _IEC_ values.
1
1 26.2.3 Examples of using ‘numfmt’
1 ---------------------------------
1
1 Converting a single number from/to _human_ representation:
1 $ numfmt --to=si 500000
1 500K
1
1 $ numfmt --to=iec 500000
1 489K
1
1 $ numfmt --to=iec-i 500000
1 489Ki
1
1 $ numfmt --from=si 1M
1 1000000
1
1 $ numfmt --from=iec 1M
1 1048576
1
1 # with '--from=auto', M=Mega, Mi=Mebi
1 $ numfmt --from=auto 1M
1 1000000
1 $ numfmt --from=auto 1Mi
1 1048576
1
1 Converting from ‘SI’ to ‘IEC’ scales (e.g. when a harddisk capacity
1 is advertised as ‘1TB’, while checking the drive’s capacity gives lower
1 values):
1
1 $ numfmt --from=si --to=iec 1T
1 932G
1
1 Converting a single field from an input file / piped input (these
1 contrived examples are for demonstration purposes only, as both ‘ls’ and
1 ‘df’ support the ‘--human-readable’ option to output sizes in
1 human-readable format):
1
1 # Third field (file size) will be shown in SI representation
1 $ ls -log | numfmt --field 3 --header --to=si | head -n4
1 -rw-r--r-- 1 94K Aug 23 2011 ABOUT-NLS
1 -rw-r--r-- 1 3.7K Jan 7 16:15 AUTHORS
1 -rw-r--r-- 1 36K Jun 1 2011 COPYING
1 -rw-r--r-- 1 0 Jan 7 15:15 ChangeLog
1
1 # Second field (size) will be shown in IEC representation
1 $ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4
1 File system 1B-blocks Used Available Use% Mounted on
1 rootfs 132G 104741408 26554036 80% /
1 tmpfs 794M 7580 804960 1% /run/shm
1 /dev/sdb1 694G 651424756 46074696 94% /home
1
1 Output can be tweaked using ‘--padding’ or ‘--format’:
1
1 # Pad to 10 characters, right-aligned
1 $ du -s * | numfmt --to=si --padding=10
1 2.5K config.log
1 108 config.status
1 1.7K configure
1 20 configure.ac
1
1 # Pad to 10 characters, left-aligned
1 $ du -s * | numfmt --to=si --padding=-10
1 2.5K config.log
1 108 config.status
1 1.7K configure
1 20 configure.ac
1
1 # Pad to 10 characters, left-aligned, using 'format'
1 $ du -s * | numfmt --to=si --format="%10f"
1 2.5K config.log
1 108 config.status
1 1.7K configure
1 20 configure.ac
1
1 # Pad to 10 characters, left-aligned, using 'format'
1 $ du -s * | numfmt --to=si --padding="%-10f"
1 2.5K config.log
1 108 config.status
1 1.7K configure
1 20 configure.ac
1
1 With locales that support grouping digits, using ‘--grouping’ or
1 ‘--format’ enables grouping. In ‘POSIX’ locale, grouping is silently
1 ignored:
1
1 $ LC_ALL=C numfmt --from=iec --grouping 2G
1 2147483648
1
1 $ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G
1 2,147,483,648
1
1 $ LC_ALL=ta_IN numfmt --from=iec --grouping 2G
1 2,14,74,83,648
1
1 $ LC_ALL=C ./src/numfmt --from=iec --format="==%'15f==" 2G
1 == 2147483648==
1
1 $ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'15f==" 2G
1 == 2,147,483,648==
1
1 $ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'-15f==" 2G
1 ==2,147,483,648 ==
1
1 $ LC_ALL=ta_IN ./src/numfmt --from=iec --format="==%'15f==" 2G
1 == 2,14,74,83,648==
1