Debian Codegraph @

upstream/debian-unstable/man1/numfmt.1

raw
1 .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.50.1.
2 .TH NUMFMT "1" "February 2026" "GNU coreutils 9.10" "User Commands"
3 .\" Define monospaced roman font for groff in troff mode.
4 .if t .if \n(.g \{\
5 . ds mono \f(CR
6 . ds /mono \fP
7 .\}
8 .SH NAME
9 numfmt \- Convert numbers from/to human-readable strings
10 .SH SYNOPSIS
11 .B numfmt
12 [\fI\,OPTION\/\fR]... [\fI\,NUMBER\/\fR]...
13 .SH DESCRIPTION
14 .\" Add any additional description here
15 .PP
16 Reformat NUMBER(s), or the numbers from standard input if none are specified.
17 .PP
18 Mandatory arguments to long options are mandatory for short options too.
19 .TP
20 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--debug'\fB\-\-debug\fP\X'tty: link'
21 print warnings about invalid input
22 .TP
23 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt-d'\fB\-d, \-\-delimiter=\,X\fP\X'tty: link'\/\fR
24 use X instead of whitespace for field delimiter
25 .TP
26 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--field'\fB\-\-field=FIELDS\fP\X'tty: link'
27 replace the numbers in these input fields (default=1);
28 see FIELDS below for details
29 .TP
30 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--format'\fB\-\-format=FORMAT\fP\X'tty: link'
31 use printf style floating\-point FORMAT;
32 see FORMAT below for details
33 .TP
34 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--from'\fB\-\-from=UNIT\fP\X'tty: link'
35 auto\-scale input numbers to UNITs; default is 'none';
36 see UNIT below for details
37 .TP
38 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--from-unit'\fB\-\-from\-unit=N\fP\X'tty: link'
39 specify the input unit size (instead of the default 1)
40 .TP
41 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--grouping'\fB\-\-grouping\fP\X'tty: link'
42 use locale\-defined grouping of digits, e.g. 1,000,000.
43 This has no effect in the C/POSIX locale
44 .TP
45 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--header'\fB\-\-header[=N]\fP\X'tty: link'
46 print (without converting) the first N header lines;
47 N defaults to 1 if not specified
48 .TP
49 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--invalid'\fB\-\-invalid=MODE\fP\X'tty: link'
50 failure mode for invalid numbers;
51 MODE can be: abort (default), fail, warn, ignore
52 .TP
53 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--padding'\fB\-\-padding=N\fP\X'tty: link'
54 pad the output to N characters;
55 positive N will right\-align, negative N will left\-align;
56 padding is ignored if the output is wider than N;
57 the default is to automatically pad if a whitespace is found
58 .TP
59 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--round'\fB\-\-round=METHOD\fP\X'tty: link'
60 use METHOD for rounding when scaling; METHOD can be:
61 up, down, from\-zero (default), towards\-zero, nearest
62 .TP
63 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--suffix'\fB\-\-suffix=SUFFIX\fP\X'tty: link'
64 add SUFFIX to output numbers,
65 and accept an optional SUFFIX in input numbers
66 .TP
67 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--unit-separator'\fB\-\-unit\-separator=SEP\fP\X'tty: link'
68 insert SEP between number and unit on output,
69 and accept an optional SEP in input numbers
70 .TP
71 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--to'\fB\-\-to=UNIT\fP\X'tty: link'
72 auto\-scale output numbers to UNITs; see UNIT below
73 .TP
74 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--to-unit'\fB\-\-to\-unit=N\fP\X'tty: link'
75 the output unit size (instead of the default 1)
76 .TP
77 \X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt-z'\fB\-z, \-\-zero\-terminated\fP\X'tty: link'
78 line delimiter is NUL, not newline
79 .TP
80 \X'tty: link https://www.gnu.org/software/coreutils/numfmt#numfmt--help'\fB\-\-help\fP\X'tty: link'
81 display this help and exit
82 .TP
83 \X'tty: link https://www.gnu.org/software/coreutils/numfmt#numfmt--version'\fB\-\-version\fP\X'tty: link'
84 output version information and exit
85 .SS "UNIT options:"
86 .TP
87 none
88 no auto\-scaling is done; suffixes will trigger an error
89 .TP
90 auto
91 accept optional single/two letter suffix:
92 1K = 1000, 1k = 1000,
93 1Ki = 1024,
94 1M = 1000000,
95 1Mi = 1048576,
96 .TP
97 si
98 accept optional single letter suffix:
99 1k = 1000, 1K = 1000,
100 1M = 1000000,
101 \&...
102 .TP
103 iec
104 accept optional single letter suffix:
105 1K = 1024, 1k = 1024,
106 1M = 1048576,
107 \&...
108 .TP
109 iec\-i
110 accept optional two\-letter suffix:
111 1Ki = 1024, 1ki = 1024,
112 1Mi = 1048576,
113 \&...
114 .SS "FIELDS supports \fBcut\fP(1) style field ranges:"
115 .TP
116 N
117 N'th field, counted from 1
118 .TP
119 N\-
120 from N'th field, to end of line
121 .TP
122 N\-M
123 from N'th to M'th field (inclusive)
124 .TP
125 \fB\-M\fR
126 from first to M'th field (inclusive)
127 .TP
128 \-
129 all fields
130 .PP
131 Multiple fields/ranges can be separated with commas
132 .PP
133 FORMAT must be suitable for printing one floating\-point argument '%f'.
134 Optional quote (%'f) will enable \fB\-\-grouping\fR (if supported by current locale).
135 Optional width value (%10f) will pad output. Optional zero (%010f) width
136 will zero pad the number. Optional negative values (%\-10f) will left align.
137 Optional precision (%.1f) will override the input determined precision.
138 .PP
139 Exit status is 0 if all input numbers were successfully converted.
140 By default, numfmt will stop at the first conversion error with exit status 2.
141 With \fB\-\-invalid\fR=\fI\,'fail'\/\fR a warning is printed for each conversion error
142 and the exit status is 2. With \fB\-\-invalid\fR=\fI\,'warn'\/\fR each conversion error is
143 diagnosed, but the exit status is 0. With \fB\-\-invalid\fR=\fI\,'ignore'\/\fR conversion
144 errors are not diagnosed and the exit status is 0.
145 .SH EXAMPLES
146 .IP
147 \*[mono]$ numfmt --to=si 1000\*[/mono]
148 .IP
149 \-> "1.0k"
150 .IP
151 \*[mono]$ numfmt --to=iec 2048\*[/mono]
152 .IP
153 \-> "2.0K"
154 .IP
155 \*[mono]$ numfmt --to=iec-i 4096\*[/mono]
156 .IP
157 \-> "4.0Ki"
158 .IP
159 \*[mono]$ echo 1K | numfmt --from=si\*[/mono]
160 .IP
161 \-> "1000"
162 .IP
163 \*[mono]$ echo 1K | numfmt --from=iec\*[/mono]
164 .IP
165 \-> "1024"
166 .IP
167 \*[mono]$ df -B1 | numfmt --header --field 2-4 --to=si\*[/mono]
168 .br
169 \*[mono]$ ls -l | numfmt --header --field 5 --to=iec\*[/mono]
170 .br
171 \*[mono]$ ls -lh | numfmt --header --field 5 --from=iec --padding=10\*[/mono]
172 .br
173 \*[mono]$ ls -lh | numfmt --header --field 5 --from=iec --format %10f\*[/mono]
174 .SH AUTHOR
175 Written by Assaf Gordon.
176 .SH "REPORTING BUGS"
177 Report bugs to: bug\[email protected]
178 .br
179 GNU coreutils home page: <https://www.gnu.org/software/coreutils/>
180 .br
181 General help using GNU software: <https://www.gnu.org/gethelp/>
182 .br
183 Report any translation bugs to <https://translationproject.org/team/>
184 .SH "SEE ALSO"
185 Full documentation <https://www.gnu.org/software/coreutils/numfmt>
186 .br
187 or available locally via: info \(aq(coreutils) numfmt invocation\(aq
188 .PP
189 .br
190 Packaged by Debian (9.10\-1)
191 .br
192 Copyright \(co 2026 Free Software Foundation, Inc.
193 .br
194 License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
195 .br
196 This is free software: you are free to change and redistribute it.
197 .br
198 There is NO WARRANTY, to the extent permitted by law.