original/man1/numfmt.1

   1 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.35.
   2 .TH NUMFMT "1" "May 2014" "GNU coreutils 8.21" "User Commands"
   3 .SH NAME
   4 numfmt \- Convert numbers from/to human-readable strings
   5 .SH SYNOPSIS
   6 .B numfmt
   7 [\fIOPTION\fR]... [\fINUMBER\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=\fIX\fR
  19 use X instead of whitespace for field delimiter
  20 .TP
  21 \fB\-\-field\fR=\fIN\fR
  22 replace the number in input field N (default is 1)
  23 .TP
  24 \fB\-\-format\fR=\fIFORMAT\fR
  25 use printf style floating\-point FORMAT;
  26 see FORMAT below for details
  27 .TP
  28 \fB\-\-from\fR=\fIUNIT\fR
  29 auto\-scale input numbers to UNITs; default is 'none';
  30 see UNIT below
  31 .TP
  32 \fB\-\-from\-unit\fR=\fIN\fR
  33 specify the input unit size (instead of the default 1)
  34 .TP
  35 \fB\-\-grouping\fR
  36 use locale\-defined grouping of digits, e.g. 1,000,000
  37 (which means it has no effect in the C/POSIX locale)
  38 .TP
  39 \fB\-\-header\fR[=\fIN\fR]
  40 print (without converting) the first N header lines;
  41 N defaults to 1 if not specified
  42 .TP
  43 \fB\-\-invalid\fR=\fIMODE\fR
  44 failure mode for invalid numbers: MODE can be:
  45 abort (default), fail, warn, ignore
  46 .TP
  47 \fB\-\-padding\fR=\fIN\fR
  48 pad the output to N characters; positive N will
  49 right\-align; negative N will left\-align;
  50 padding is ignored if the output is wider than N;
  51 the default is to automatically pad if a whitespace
  52 is found
  53 .TP
  54 \fB\-\-round\fR=\fIMETHOD\fR
  55 use METHOD for rounding when scaling; METHOD can be:
  56 up, down, from\-zero (default), towards\-zero, nearest
  57 .TP
  58 \fB\-\-suffix\fR=\fISUFFIX\fR
  59 add SUFFIX to output numbers, and accept optional
  60 SUFFIX in input numbers
  61 .TP
  62 \fB\-\-to\fR=\fIUNIT\fR
  63 auto\-scale output numbers to UNITs; see UNIT below
  64 .TP
  65 \fB\-\-to\-unit\fR=\fIN\fR
  66 the output unit size (instead of the default 1)
  67 .TP
  68 \fB\-\-help\fR
  69 display this help and exit
  70 .TP
  71 \fB\-\-version\fR
  72 output version information and exit
  73 .SS "UNIT options:"
  74 .TP
  75 none
  76 no auto\-scaling is done; suffixes will trigger an error
  77 .TP
  78 auto
  79 accept optional single/two letter suffix:
  80 .IP
  81 1K = 1000,
  82 1Ki = 1024,
  83 1M = 1000000,
  84 1Mi = 1048576,
  85 .TP
  86 si
  87 accept optional single letter suffix:
  88 .IP
  89 1K = 1000,
  90 1M = 1000000,
  91 \&...
  92 .TP
  93 iec
  94 accept optional single letter suffix:
  95 .IP
  96 1K = 1024,
  97 1M = 1048576,
  98 \&...
  99 .TP
 100 iec\-i
 101 accept optional two\-letter suffix:
 102 .IP
 103 1Ki = 1024,
 104 1Mi = 1048576,
 105 \&...
 106 .PP
 107 FORMAT must be suitable for printing one floating\-point argument '%f'.
 108 Optional quote (%'f) will enable \fB\-\-grouping\fR (if supported by current locale).
 109 Optional width value (%10f) will pad output. Optional negative width values
 110 (%\-10f) will left\-pad output.
 111 .PP
 112 Exit status is 0 if all input numbers were successfully converted.
 113 By default, numfmt will stop at the first conversion error with exit status 2.
 114 With \fB\-\-invalid=\fR'fail' a warning is printed for each conversion error
 115 and the exit status is 2.  With \fB\-\-invalid=\fR'warn' each conversion error is
 116 diagnosed, but the exit status is 0.  With \fB\-\-invalid=\fR'ignore' conversion
 117 errors are not diagnosed and the exit status is 0.
 118 .SH EXAMPLES
 119 .IP
 120 \f(CW$ numfmt --to=si 1000\fR
 121 .IP
 122 \-> "1.0K"
 123 .IP
 124 \f(CW$ numfmt --to=iec 2048\fR
 125 .IP
 126 \-> "2.0K"
 127 .IP
 128 \f(CW$ numfmt --to=iec-i 4096\fR
 129 .IP
 130 \-> "4.0Ki"
 131 .IP
 132 \f(CW$ echo 1K | numfmt --from=si\fR
 133 .IP
 134 \-> "1000"
 135 .IP
 136 \f(CW$ echo 1K | numfmt --from=iec\fR
 137 .IP
 138 \-> "1024"
 139 .IP
 140 \f(CW$ df | numfmt --header --field 2 --to=si\fR
 141 .br
 142 \f(CW$ ls -l | numfmt --header --field 5 --to=iec\fR
 143 .br
 144 \f(CW$ ls -lh | numfmt --header --field 5 --from=iec --padding=10\fR
 145 .br
 146 \f(CW$ ls -lh | numfmt --header --field 5 --from=iec --format %10f\fR
 147 .SH AUTHOR
 148 Written by Assaf Gordon.
 149 .SH "REPORTING BUGS"
 150 Report numfmt bugs to bug\-coreutils@gnu.org
 151 .br
 152 GNU coreutils home page: <http://www.gnu.org/software/coreutils/>
 153 .br
 154 General help using GNU software: <http://www.gnu.org/gethelp/>
 155 .br
 156 Report numfmt translation bugs to <http://translationproject.org/team/>
 157 .SH COPYRIGHT
 158 Copyright \(co 2013 Free Software Foundation, Inc.
 159 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
 160 .br
 161 This is free software: you are free to change and redistribute it.
 162 There is NO WARRANTY, to the extent permitted by law.
 163 .SH "SEE ALSO"
 164 The full documentation for
 165 .B numfmt
 166 is maintained as a Texinfo manual.  If the
 167 .B info
 168 and
 169 .B numfmt
 170 programs are properly installed at your site, the command
 171 .IP
 172 .B info coreutils \(aqnumfmt invocation\(aq
 173 .PP
 174 should give you access to the complete manual.