numfmt(1)

1NUMFMT(1)                        User Commands                       NUMFMT(1)
2
3
4

NAME

6       numfmt - Convert numbers from/to human-readable strings
7

SYNOPSIS

9       numfmt [OPTION]... [NUMBER]...
10

DESCRIPTION

12       Reformat  NUMBER(s),  or  the  numbers  from standard input if none are
13       specified.
14
15       Mandatory arguments to long options are  mandatory  for  short  options
16       too.
17
18       --debug
19              print warnings about invalid input
20
21       -d, --delimiter=X
22              use X instead of whitespace for field delimiter
23
24       --field=FIELDS
25              replace  the  numbers  in  these  input  fields (default=1); see
26              FIELDS below
27
28       --format=FORMAT
29              use printf style floating-point FORMAT; see FORMAT below for de‐
30              tails
31
32       --from=UNIT
33              auto-scale  input  numbers to UNITs; default is 'none'; see UNIT
34              below
35
36       --from-unit=N
37              specify the input unit size (instead of the default 1)
38
39       --grouping
40              use locale-defined grouping of  digits,  e.g.  1,000,000  (which
41              means it has no effect in the C/POSIX locale)
42
43       --header[=N]
44              print  (without converting) the first N header lines; N defaults
45              to 1 if not specified
46
47       --invalid=MODE
48              failure mode for invalid numbers: MODE can be: abort  (default),
49              fail, warn, ignore
50
51       --padding=N
52              pad  the  output  to  N characters; positive N will right-align;
53              negative N will left-align; padding is ignored if the output  is
54              wider  than  N;  the default is to automatically pad if a white‐
55              space is found
56
57       --round=METHOD
58              use METHOD for rounding when scaling; METHOD can be:  up,  down,
59              from-zero (default), towards-zero, nearest
60
61       --suffix=SUFFIX
62              add  SUFFIX to output numbers, and accept optional SUFFIX in in‐
63              put numbers
64
65       --to=UNIT
66              auto-scale output numbers to UNITs; see UNIT below
67
68       --to-unit=N
69              the output unit size (instead of the default 1)
70
71       -z, --zero-terminated
72              line delimiter is NUL, not newline
73
74       --help display this help and exit
75
76       --version
77              output version information and exit
78
79   UNIT options:
80       none   no auto-scaling is done; suffixes will trigger an error
81
82       auto   accept optional single/two letter suffix:
83
84              1K = 1000, 1Ki = 1024, 1M = 1000000, 1Mi = 1048576,
85
86       si     accept optional single letter suffix:
87
88              1K = 1000, 1M = 1000000, ...
89
90       iec    accept optional single letter suffix:
91
92              1K = 1024, 1M = 1048576, ...
93
94       iec-i  accept optional two-letter suffix:
95
96              1Ki = 1024, 1Mi = 1048576, ...
97
98   FIELDS supports cut(1) style field ranges:
99       N      N'th field, counted from 1
100
101       N-     from N'th field, to end of line
102
103       N-M    from N'th to M'th field (inclusive)
104
105       -M     from first to M'th field (inclusive)
106
107       -      all fields
108
109       Multiple fields/ranges can be separated with commas
110
111       FORMAT must be suitable for printing one floating-point argument  '%f'.
112       Optional  quote  (%'f)  will enable --grouping (if supported by current
113       locale).  Optional width value (%10f) will pad  output.  Optional  zero
114       (%010f)  width  will  zero  pad  the  number.  Optional negative values
115       (%-10f) will left align.  Optional precision (%.1f) will  override  the
116       input determined precision.
117
118       Exit  status is 0 if all input numbers were successfully converted.  By
119       default, numfmt will stop at the first conversion error with exit  sta‐
120       tus  2.  With --invalid='fail' a warning is printed for each conversion
121       error and the exit status is 2.  With --invalid='warn' each  conversion
122       error  is diagnosed, but the exit status is 0.  With --invalid='ignore'
123       conversion errors are not diagnosed and the exit status is 0.
124

EXAMPLES

126              $ numfmt --to=si 1000
127
128              -> "1.0K"
129
130              $ numfmt --to=iec 2048
131
132              -> "2.0K"
133
134              $ numfmt --to=iec-i 4096
135
136              -> "4.0Ki"
137
138              $ echo 1K | numfmt --from=si
139
140              -> "1000"
141
142              $ echo 1K | numfmt --from=iec
143
144              -> "1024"
145
146              $ df -B1 | numfmt --header --field 2-4 --to=si
147              $ ls -l  | numfmt --header --field 5 --to=iec
148              $ ls -lh | numfmt --header --field 5 --from=iec --padding=10
149              $ ls -lh | numfmt --header --field 5 --from=iec --format %10f
150

AUTHOR

152       Written by Assaf Gordon.
153

REPORTING BUGS

155       GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
156       Report any translation bugs to <https://translationproject.org/team/>
157

COPYRIGHT

159       Copyright © 2021 Free Software Foundation, Inc.   License  GPLv3+:  GNU
160       GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
161       This  is  free  software:  you  are free to change and redistribute it.
162       There is NO WARRANTY, to the extent permitted by law.
163