2239
@node numfmt invocation
2240
@section @command{numfmt}: Reformat numbers
2244
@command{numfmt} reads numbers in various representations and reformats them
2245
as requested. The most common usage is converting numbers to/from @emph{human}
2246
representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}).
2249
numfmt [@var{option}]@dots{} [@var{number}]
2252
@command{numfmt} converts each @var{number} on the command-line according to the
2253
specified options (see below). If no @var{number}s are given, it reads numbers
2254
from standard input. @command{numfmt} can optionally extract numbers from
2255
specific columns, maintaining proper line padding and alignment.
2259
See @option{--invalid} for additional information regarding exit status.
2261
@subsection General options
2263
The program accepts the following options. Also see @ref{Common options}.
2269
Print (to standard error) warning messages about possible erroneous usage.
2272
@itemx --delimiter=@var{d}
2274
@opindex --delimiter
2275
Use the character @var{d} as input field separator (default: whitespace).
2276
@emph{Note}: Using non-default delimiter turns off automatic padding.
2278
@item --field=@var{n}
2280
Convert the number in input field @var{n} (default: 1).
2282
@item --format=@var{format}
2284
Use printf-style floating FORMAT string. The @var{format} string must contain
2285
one @samp{%f} directive, optionally with @samp{'}, @samp{-}, or width
2286
modifiers. The @samp{'} modifier will enable @option{--grouping}, the @samp{-}
2287
modifier will enable left-aligned @option{--padding} and the width modifier will
2288
enable right-aligned @option{--padding}.
2290
@item --from=@var{unit}
2292
Auto-scales input numbers according to @var{unit}. See UNITS below.
2293
The default is no scaling, meaning suffixes (e.g. @samp{M}, @samp{G}) will
2296
@item --from-unit=@var{n}
2297
@opindex --from-unit
2298
Specify the input unit size (instead of the default 1). Use this option when
2299
the input numbers represent other units (e.g. if the input number @samp{10}
2300
represents 10 units of 512 bytes, use @samp{--from=unit=512}).
2304
Group digits in output numbers according to the current locale's grouping rules
2305
(e.g @emph{Thousands Separator} character, commonly @samp{.} (dot) or @samp{,}
2306
comma). This option has no effect in @samp{POSIX/C} locale.
2308
@item --header[=@var{n}]
2311
Print the first @var{n} (default: 1) lines without any conversion.
2313
@item --invalid=@var{mode}
2315
The default action on input errors is to exit immediately with status code 2.
2316
@option{--invalid=@samp{abort}} explicitly specifies this default mode.
2317
With a @var{mode} of @samp{fail}, print a warning for @emph{each} conversion
2318
error, and exit with status 2. With a @var{mode} of @samp{warn}, exit with
2319
status 0, even in the presence of conversion errors, and with a @var{mode} of
2320
@samp{ignore} do not even print diagnostics.
2322
@item --padding=@var{n}
2324
Pad the output numbers to @var{n} characters, by adding spaces. If @var{n} is
2325
a positive number, numbers will be right-aligned. If @var{n} is a negative
2326
number, numbers will be left-aligned. By default, numbers are automatically
2327
aligned based on the input line's width (only with the default delimiter).
2329
@item --round=@var{method}
2332
@opindex --round=down
2333
@opindex --round=from-zero
2334
@opindex --round=towards-zero
2335
@opindex --round=nearest
2336
When converting number representations, round the number according to
2337
@var{method}, which can be @samp{up}, @samp{down},
2338
@samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}.
2340
@item --suffix=@var{suffix}
2342
Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in
2345
@item --to=@var{unit}
2347
Auto-scales output numbers according to @var{unit}. See @emph{Units} below.
2348
The default is no scaling, meaning all the digits of the number are printed.
2350
@item --to-unit=@var{n}
2352
Specify the output unit size (instead of the default 1). Use this option when
2353
the output numbers represent other units (e.g. to represent @samp{4,000,000}
2354
bytes in blocks of 1KB, use @samp{--to=si --to=units=1000}).
2358
@subsection Possible @var{unit}s:
2360
The following are the possible @var{unit} options with @option{--from=UNITS} and
2361
@option{--to=UNITS}:
2366
No scaling is performed. For input numbers, no suffixes are accepted, and any
2367
trailing characters following the number will trigger an error. For output
2368
numbers, all digits of the numbers will be printed.
2371
Auto-scale numbers according to the @emph{International System of Units (SI)}
2373
For input numbers, accept one of the following suffixes.
2374
For output numbers, values larger than 1000 will be rounded, and printed with
2375
one of the following suffixes:
2378
@samp{K} => @math{1000^1 = 10^3} (Kilo)
2379
@samp{M} => @math{1000^2 = 10^6} (Mega)
2380
@samp{G} => @math{1000^3 = 10^9} (Giga)
2381
@samp{T} => @math{1000^4 = 10^{12}} (Tera)
2382
@samp{P} => @math{1000^5 = 10^{15}} (Peta)
2383
@samp{E} => @math{1000^6 = 10^{18}} (Exa)
2384
@samp{Z} => @math{1000^7 = 10^{21}} (Zetta)
2385
@samp{Y} => @math{1000^8 = 10^{24}} (Yotta)
2389
Auto-scale numbers according to the @emph{International Electronical
2390
Commission (IEC)} standard.
2391
For input numbers, accept one of the following suffixes.
2392
For output numbers, values larger than 1024 will be rounded, and printed with
2393
one of the following suffixes:
2396
@samp{K} => @math{1024^1 = 2^{10}} (Kibi)
2397
@samp{M} => @math{1024^2 = 2^{20}} (Mebi)
2398
@samp{G} => @math{1024^3 = 2^{30}} (Gibi)
2399
@samp{T} => @math{1024^4 = 2^{40}} (Tebi)
2400
@samp{P} => @math{1024^5 = 2^{50}} (Pebi)
2401
@samp{E} => @math{1024^6 = 2^{60}} (Exbi)
2402
@samp{Z} => @math{1024^7 = 2^{70}} (Zebi)
2403
@samp{Y} => @math{1024^8 = 2^{80}} (Yobi)
2406
The @option{iec} option uses a single letter suffix (e.g. @samp{G}), which is
2407
not fully standard, as the @emph{iec} standard recommends a two-letter symbol
2408
(e.g @samp{Gi}) - but in practice, this method common. Compare with
2409
the @option{iec-i} option.
2412
Auto-scale numbers according to the @emph{International Electronical
2413
Commission (IEC)} standard.
2414
For input numbers, accept one of the following suffixes.
2415
For output numbers, values larger than 1024 will be rounded, and printed with
2416
one of the following suffixes:
2419
@samp{Ki} => @math{1024^1 = 2^{10}} (Kibi)
2420
@samp{Mi} => @math{1024^2 = 2^{20}} (Mebi)
2421
@samp{Gi} => @math{1024^3 = 2^{30}} (Gibi)
2422
@samp{Ti} => @math{1024^4 = 2^{40}} (Tebi)
2423
@samp{Pi} => @math{1024^5 = 2^{50}} (Pebi)
2424
@samp{Ei} => @math{1024^6 = 2^{60}} (Exbi)
2425
@samp{Zi} => @math{1024^7 = 2^{70}} (Zebi)
2426
@samp{Yi} => @math{1024^8 = 2^{80}} (Yobi)
2429
The @option{iec-i} option uses a two-letter suffix symbol (e.g. @samp{Gi}),
2430
as the @emph{iec} standard recommends, but this is not always common in
2431
practice. Compare with the @option{iec} option.
2434
@samp{auto} can only be used with @option{--from}. With this method, numbers
2435
with @samp{K},@samp{M},@samp{G},@samp{T},@samp{P},@samp{E},@samp{Z},@samp{Y}
2436
suffixes are interpreted as @emph{SI} values, and numbers with @samp{Ki},
2437
@samp{Mi},@samp{Gi},@samp{Ti},@samp{Pi},@samp{Ei},@samp{Zi},@samp{Yi} suffixes
2438
are interpreted as @emph{IEC} values.
2442
@subsection Examples of using @command{numfmt}
2444
Converting a single number from/to @emph{human} representation:
2446
$ nunfmt --to=si 500000
2449
$ numfmt --to=iec 500000
2452
$ numfmt --to=iec-i 500000
2455
$ numfmt --from=si 1M
2458
$ numfmt --from=iec 1M
2461
# with '--from=auto', M=Mega, Mi=Mebi
2462
$ numfmt --from=auto 1M
2464
$ numfmt --from=auto 1Mi
2468
Converting from @samp{SI} to @samp{IEC} scales (e.g. when a harddisk capacity is
2469
advertised as @samp{1TB}, while checking the drive's capacity gives lower
2473
$ numfmt --from=si --to=iec 1T
2478
Converting a single field from an input file / piped input (these contrived
2479
examples are for demonstration purposes only, as both @command{ls} and
2480
@command{df} support the @option{--human-readable} option to
2481
output sizes in human-readable format):
2484
# Third field (file size) will be shown in SI representation
2485
$ ls -log | numfmt --field 3 --header --to=si | head -n4
2486
-rw-r--r-- 1 94K Aug 23 2011 ABOUT-NLS
2487
-rw-r--r-- 1 3.7K Jan 7 16:15 AUTHORS
2488
-rw-r--r-- 1 36K Jun 1 2011 COPYING
2489
-rw-r--r-- 1 0 Jan 7 15:15 ChangeLog
2491
# Second field (size) will be shown in IEC representation
2492
$ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4
2493
File system 1B-blocks Used Available Use% Mounted on
2494
rootfs 132G 104741408 26554036 80% /
2495
tmpfs 794M 7580 804960 1% /run/shm
2496
/dev/sdb1 694G 651424756 46074696 94% /home
2500
Output can be tweaked using @option{--padding} or @option{--format}:
2503
# Pad to 10 characters, right-aligned
2504
$ du -s * | numfmt --to=si --padding=10
2510
# Pad to 10 characters, left-aligned
2511
$ du -s * | numfmt --to=si --padding=-10
2517
# Pad to 10 characters, left-aligned, using 'format'
2518
$ du -s * | numfmt --to=si --format="%10f"
2524
# Pad to 10 characters, left-aligned, using 'format'
2525
$ du -s * | numfmt --to=si --padding="%-10f"
2532
With locales that support grouping digits, using @option{--grouping} or
2533
@option{--format} enables grouping. In @samp{POSIX} locale, grouping is
2537
$ LC_ALL=C numfmt --from=iec --grouping 2G
2540
$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G
2543
$ LC_ALL=ta_IN numfmt --from=iec --grouping 2G
2546
$ LC_ALL=C ./src/numfmt --from=iec --format="==%'15f==" 2G
2549
$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'15f==" 2G
2552
$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'-15f==" 2G
2555
$ LC_ALL=ta_IN ./src/numfmt --from=iec --format="==%'15f==" 2G
2227
2559
@node pr invocation
2228
2560
@section @command{pr}: Paginate or columnate files for printing
added
removed
doc/coreutils.texi
