.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH NUMFMT "1" "January 2023" "GNU coreutils 9.1" "User Commands"
.SH NAME
numfmt \- manual page for numfmt 9.1
.SH SYNOPSIS
.B numfmt
[\fI\,OPTION\/\fR]... [\fI\,NUMBER\/\fR]...
.SH DESCRIPTION
Reformat NUMBER(s), or the numbers from standard input if none are specified.
.PP
Mandatory arguments to long options are mandatory for short options too.
.TP
\fB\-\-debug\fR
print warnings about invalid input
.TP
\fB\-d\fR, \fB\-\-delimiter\fR=\fI\,X\/\fR
use X instead of whitespace for field delimiter
.TP
\fB\-\-field\fR=\fI\,FIELDS\/\fR
replace the numbers in these input fields (default=1);
see FIELDS below
.TP
\fB\-\-format\fR=\fI\,FORMAT\/\fR
use printf style floating\-point FORMAT;
see FORMAT below for details
.TP
\fB\-\-from\fR=\fI\,UNIT\/\fR
auto\-scale input numbers to UNITs; default is 'none';
see UNIT below
.TP
\fB\-\-from\-unit\fR=\fI\,N\/\fR
specify the input unit size (instead of the default 1)
.TP
\fB\-\-grouping\fR
use locale\-defined grouping of digits, e.g. 1,000,000
(which means it has no effect in the C/POSIX locale)
.TP
\fB\-\-header\fR[=\fI\,N\/\fR]
print (without converting) the first N header lines;
N defaults to 1 if not specified
.TP
\fB\-\-invalid\fR=\fI\,MODE\/\fR
failure mode for invalid numbers: MODE can be:
abort (default), fail, warn, ignore
.TP
\fB\-\-padding\fR=\fI\,N\/\fR
pad the output to N characters; positive N will
right\-align; negative N will left\-align;
padding is ignored if the output is wider than N;
the default is to automatically pad if a whitespace
is found
.TP
\fB\-\-round\fR=\fI\,METHOD\/\fR
use METHOD for rounding when scaling; METHOD can be:
up, down, from\-zero (default), towards\-zero, nearest
.TP
\fB\-\-suffix\fR=\fI\,SUFFIX\/\fR
add SUFFIX to output numbers, and accept optional
SUFFIX in input numbers
.TP
\fB\-\-to\fR=\fI\,UNIT\/\fR
auto\-scale output numbers to UNITs; see UNIT below
.TP
\fB\-\-to\-unit\fR=\fI\,N\/\fR
the output unit size (instead of the default 1)
.TP
\fB\-z\fR, \fB\-\-zero\-terminated\fR
line delimiter is NUL, not newline
.TP
\fB\-\-help\fR
display this help and exit
.TP
\fB\-\-version\fR
output version information and exit
.SS "UNIT options:"
.TP
none
no auto\-scaling is done; suffixes will trigger an error
.TP
auto
accept optional single/two letter suffix:
.IP
1K = 1000,
1Ki = 1024,
1M = 1000000,
1Mi = 1048576,
.TP
si
accept optional single letter suffix:
.IP
1K = 1000,
1M = 1000000,
\&...
.TP
iec
accept optional single letter suffix:
.IP
1K = 1024,
1M = 1048576,
\&...
.TP
iec\-i
accept optional two\-letter suffix:
.IP
1Ki = 1024,
1Mi = 1048576,
\&...
.SS "FIELDS supports cut(1) style field ranges:"
.TP
N
N'th field, counted from 1
.TP
N\-
from N'th field, to end of line
.TP
N\-M
from N'th to M'th field (inclusive)
.TP
\fB\-M\fR
from first to M'th field (inclusive)
.TP
\-
all fields
.PP
Multiple fields/ranges can be separated with commas
.PP
FORMAT must be suitable for printing one floating\-point argument '%f'.
Optional quote (%'f) will enable \fB\-\-grouping\fR (if supported by current locale).
Optional width value (%10f) will pad output. Optional zero (%010f) width
will zero pad the number. Optional negative values (%\-10f) will left align.
Optional precision (%.1f) will override the input determined precision.
.PP
Exit status is 0 if all input numbers were successfully converted.
By default, numfmt will stop at the first conversion error with exit status 2.
With \fB\-\-invalid=\fR'fail' a warning is printed for each conversion error
and the exit status is 2.  With \fB\-\-invalid=\fR'warn' each conversion error is
diagnosed, but the exit status is 0.  With \fB\-\-invalid=\fR'ignore' conversion
errors are not diagnosed and the exit status is 0.
.SH EXAMPLES
.IP
\f(CW$ numfmt --to=si 1000\fR
.IP
\-> "1.0K"
.IP
\f(CW$ numfmt --to=iec 2048\fR
.IP
\-> "2.0K"
.IP
\f(CW$ numfmt --to=iec-i 4096\fR
.IP
\-> "4.0Ki"
.IP
\f(CW$ echo 1K | numfmt --from=si\fR
.IP
\-> "1000"
.IP
\f(CW$ echo 1K | numfmt --from=iec\fR
.IP
\-> "1024"
.IP
\f(CW$ df -B1 | numfmt --header --field 2-4 --to=si\fR
.br
\f(CW$ ls -l  | numfmt --header --field 5 --to=iec\fR
.br
\f(CW$ ls -lh | numfmt --header --field 5 --from=iec --padding=10\fR
.br
\f(CW$ ls -lh | numfmt --header --field 5 --from=iec --format %10f\fR
.PP
GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
Report any translation bugs to <https://translationproject.org/team/>
Full documentation <https://www.gnu.org/software/coreutils/numfmt>
or available locally via: info '(coreutils) numfmt invocation'
.SH AUTHOR
Written by Assaf Gordon.
.SH COPYRIGHT
Copyright \(co 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.