aboutsummaryrefslogtreecommitdiff
path: root/man/numfmt.1
diff options
context:
space:
mode:
authorSoccera1 <[email protected]>2026-07-28 15:54:54 +1000
committerSoccera1 <[email protected]>2026-07-28 15:54:54 +1000
commit6a2f098e72e71437154ec00506e8e736aa8e1026 (patch)
tree63e9f5596be38558dbeb40bb566735759a3ccabb /man/numfmt.1
parenta753f669c9bedfccb9f7f400da018bb487dca5d0 (diff)
downloadbnu-6a2f098e72e71437154ec00506e8e736aa8e1026.tar.gz
bnu-6a2f098e72e71437154ec00506e8e736aa8e1026.zip
Add docs
Diffstat (limited to 'man/numfmt.1')
-rw-r--r--man/numfmt.1196
1 files changed, 196 insertions, 0 deletions
diff --git a/man/numfmt.1 b/man/numfmt.1
new file mode 100644
index 0000000..079d4ef
--- /dev/null
+++ b/man/numfmt.1
@@ -0,0 +1,196 @@
+.\" Adapted for BNU from the GNU Coreutils 9.11 manual page; see doc/README.md.
+.TH NUMFMT "1" "2026-07-28" "BNU 9.11" "BNU Commands"
+.\" Define monospaced roman font for groff in troff mode.
+.if t .if \n(.g \{\
+. ds mono \f(CR
+. ds /mono \fP
+.\}
+.SH NAME
+numfmt \- Convert numbers from/to human-readable strings
+.SH SYNOPSIS
+.B numfmt
+[\fI\,OPTION\/\fR]... [\fI\,NUMBER\/\fR]...
+.SH DESCRIPTION
+.\" This page is derived from GNU Coreutils documentation.
+This page documents BNU, an independent Bun implementation compatible with
+GNU Coreutils 9.11.
+.PP
+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
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--debug'\fB\-\-debug\fP\X'tty: link'
+print warnings about invalid input
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt-d'\fB\-d, \-\-delimiter=\,X\fP\X'tty: link'\/\fR
+use X instead of whitespace for field delimiter
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--field'\fB\-\-field=FIELDS\fP\X'tty: link'
+replace the numbers in these input fields (default=1);
+see FIELDS below for details
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--format'\fB\-\-format=FORMAT\fP\X'tty: link'
+use printf style floating\-point FORMAT;
+see FORMAT below for details
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--from'\fB\-\-from=UNIT\fP\X'tty: link'
+auto\-scale input numbers to UNITs; default is 'none';
+see UNIT below for details
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--from-unit'\fB\-\-from\-unit=N\fP\X'tty: link'
+specify the input unit size (instead of the default 1)
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--grouping'\fB\-\-grouping\fP\X'tty: link'
+use locale\-defined grouping of digits, e.g. 1,000,000.
+This has no effect in the C/POSIX locale
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--header'\fB\-\-header[=N]\fP\X'tty: link'
+print (without converting) the first N header lines;
+N defaults to 1 if not specified
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--invalid'\fB\-\-invalid=MODE\fP\X'tty: link'
+failure mode for invalid numbers;
+MODE can be: abort (default), fail, warn, ignore
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--padding'\fB\-\-padding=N\fP\X'tty: link'
+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
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--round'\fB\-\-round=METHOD\fP\X'tty: link'
+use METHOD for rounding when scaling; METHOD can be:
+up, down, from\-zero (default), towards\-zero, nearest
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--suffix'\fB\-\-suffix=SUFFIX\fP\X'tty: link'
+add SUFFIX to output numbers,
+and accept an optional SUFFIX in input numbers
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--unit-separator'\fB\-\-unit\-separator=SEP\fP\X'tty: link'
+insert SEP between number and unit on output,
+and accept an optional SEP in input numbers
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--to'\fB\-\-to=UNIT\fP\X'tty: link'
+auto\-scale output numbers to UNITs; see UNIT below
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--to-unit'\fB\-\-to\-unit=N\fP\X'tty: link'
+the output unit size (instead of the default 1)
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt-z'\fB\-z, \-\-zero\-terminated\fP\X'tty: link'
+line delimiter is NUL, not newline
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/numfmt#numfmt--help'\fB\-\-help\fP\X'tty: link'
+display this help and exit
+.TP
+\X'tty: link https://www.gnu.org/software/coreutils/numfmt#numfmt--version'\fB\-\-version\fP\X'tty: link'
+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:
+1K = 1000, 1k = 1000,
+1Ki = 1024,
+1M = 1000000,
+1Mi = 1048576,
+.TP
+si
+accept optional single letter suffix:
+1k = 1000, 1K = 1000,
+1M = 1000000,
+\&...
+.TP
+iec
+accept optional single letter suffix:
+1K = 1024, 1k = 1024,
+1M = 1048576,
+\&...
+.TP
+iec\-i
+accept optional two\-letter suffix:
+1Ki = 1024, 1ki = 1024,
+1Mi = 1048576,
+\&...
+.SS "FIELDS supports \fBcut\fP(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=\fI\,'fail'\/\fR a warning is printed for each conversion error
+and the exit status is 2. With \fB\-\-invalid\fR=\fI\,'warn'\/\fR each conversion error is
+diagnosed, but the exit status is 0. With \fB\-\-invalid\fR=\fI\,'ignore'\/\fR conversion
+errors are not diagnosed and the exit status is 0.
+.SH EXAMPLES
+.IP
+\*[mono]$ numfmt --to=si 1000\*[/mono]
+.IP
+\-> "1.0k"
+.IP
+\*[mono]$ numfmt --to=iec 2048\*[/mono]
+.IP
+\-> "2.0K"
+.IP
+\*[mono]$ numfmt --to=iec-i 4096\*[/mono]
+.IP
+\-> "4.0Ki"
+.IP
+\*[mono]$ echo 1K | numfmt --from=si\*[/mono]
+.IP
+\-> "1000"
+.IP
+\*[mono]$ echo 1K | numfmt --from=iec\*[/mono]
+.IP
+\-> "1024"
+.IP
+\*[mono]$ df -B1 | numfmt --header --field 2-4 --to=si\*[/mono]
+.br
+\*[mono]$ ls -l | numfmt --header --field 5 --to=iec\*[/mono]
+.br
+\*[mono]$ ls -lh | numfmt --header --field 5 --from=iec --padding=10\*[/mono]
+.br
+\*[mono]$ ls -lh | numfmt --header --field 5 --from=iec --format %10f\*[/mono]
+.SH AUTHORS
+Upstream GNU Coreutils documentation authors:
+Written by Assaf Gordon.
+.br
+Adapted for BNU; the BNU implementation is independent.
+.SH "REPORTING BUGS"
+Report BNU bugs at <https://github.com/Soccera1/bnu/issues>.
+.br
+For upstream GNU Coreutils, see <https://www.gnu.org/software/coreutils/>.
+.SH COPYRIGHT
+Copyright \(co 2026 Free Software Foundation, Inc.
+.br
+This manual page was adapted for BNU in 2026.
+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.
+.SH "SEE ALSO"
+Upstream documentation <https://www.gnu.org/software/coreutils/numfmt>
+.br
+BNU documentation is available locally via: info \(aq(bnu) numfmt invocation\(aq