original/man1/numfmt.1

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