Debian Codegraph @

upstream/debian-trixie/man1/numfmt.1

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