From 52209ee547476aba6827848705cfa15484df78bd Mon Sep 17 00:00:00 2001 From: =?utf8?q?P=C3=A1draig=20Brady?= Date: Sat, 28 Mar 2015 16:53:15 +0000 Subject: [PATCH] doc: move numfmt info to the 'Numeric operations' section * doc/coreutils.texi: Move numfmt info to this section, as numfmt functionality aligns more with seq and factor, than fmt and pr etc. --- doc/coreutils.texi | 1403 ++++++++++++++++++++++---------------------- 1 file changed, 702 insertions(+), 701 deletions(-) diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 3cbce63c99..ac242bfab1 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -243,7 +243,6 @@ Output of entire files Formatting file contents * fmt invocation:: Reformat paragraph text -* numfmt invocation:: Reformat numbers * pr invocation:: Paginate or columnate files for printing * fold invocation:: Wrap input lines to fit in specified width @@ -461,6 +460,7 @@ Delaying Numeric operations * factor invocation:: Print prime factors +* numfmt invocation:: Reformat numbers * seq invocation:: Print numeric sequences File permissions @@ -2207,7 +2207,6 @@ These commands reformat the contents of files. @menu * fmt invocation:: Reformat paragraph text. -* numfmt invocation:: Reformat numbers. * pr invocation:: Paginate or columnate files for printing. * fold invocation:: Wrap input lines to fit in specified width. @end menu @@ -2317,508 +2316,186 @@ leaving the code unchanged. @exitstatus -@node numfmt invocation -@section @command{numfmt}: Reformat numbers +@node pr invocation +@section @command{pr}: Paginate or columnate files for printing -@pindex numfmt +@pindex pr +@cindex printing, preparing files for +@cindex multicolumn output, generating +@cindex merging files in parallel -@command{numfmt} reads numbers in various representations and reformats them -as requested. The most common usage is converting numbers to/from @emph{human} -representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}). +@command{pr} writes each @var{file} (@samp{-} means standard input), or +standard input if none are given, to standard output, paginating and +optionally outputting in multicolumn format; optionally merges all +@var{file}s, printing all in parallel, one per column. Synopsis: @example -numfmt [@var{option}]@dots{} [@var{number}] +pr [@var{option}]@dots{} [@var{file}]@dots{} @end example -@command{numfmt} converts each @var{number} on the command-line according to the -specified options (see below). If no @var{number}s are given, it reads numbers -from standard input. @command{numfmt} can optionally extract numbers from -specific columns, maintaining proper line padding and alignment. - -@exitstatus +@vindex LC_MESSAGES +By default, a 5-line header is printed at each page: two blank lines; +a line with the date, the file name, and the page count; and two more +blank lines. A footer of five blank lines is also printed. +The default @var{page_length} is 66 +lines. The default number of text lines is therefore 56. +The text line of the header takes the form +@samp{@var{date} @var{string} @var{page}}, with spaces inserted around +@var{string} so that the line takes up the full @var{page_width}. Here, +@var{date} is the date (see the @option{-D} or @option{--date-format} +option for details), @var{string} is the centered header string, and +@var{page} identifies the page number. The @env{LC_MESSAGES} locale +category affects the spelling of @var{page}; in the default C locale, it +is @samp{Page @var{number}} where @var{number} is the decimal page +number. -See @option{--invalid} for additional information regarding exit status. +Form feeds in the input cause page breaks in the output. Multiple form +feeds produce empty pages. -@subsection General options +Columns are of equal width, separated by an optional string (default +is @samp{space}). For multicolumn output, lines will always be truncated to +@var{page_width} (default 72), unless you use the @option{-J} option. +For single +column output no line truncation occurs by default. Use @option{-W} option to +truncate lines in that case. The program accepts the following options. Also see @ref{Common options}. @table @samp -@item --debug -@opindex --debug -Print (to standard error) warning messages about possible erroneous usage. - -@item -d @var{d} -@itemx --delimiter=@var{d} -@opindex -d -@opindex --delimiter -Use the character @var{d} as input field separator (default: whitespace). -@emph{Note}: Using non-default delimiter turns off automatic padding. - -@item --field=@var{n} -@opindex --field -Convert the number in input field @var{n} (default: 1). - -@item --format=@var{format} -@opindex --format -Use printf-style floating FORMAT string. The @var{format} string must contain -one @samp{%f} directive, optionally with @samp{'}, @samp{-}, @samp{0}, or width -modifiers. The @samp{'} modifier will enable @option{--grouping}, the @samp{-} -modifier will enable left-aligned @option{--padding} and the width modifier will -enable right-aligned @option{--padding}. The @samp{0} width modifier -(without the @samp{-} modifier) will generate leading zeros on the number, -up to the specified width. +@item +@var{first_page}[:@var{last_page}] +@itemx --pages=@var{first_page}[:@var{last_page}] +@c The two following @opindex lines evoke warnings because they contain ':' +@c The 'info' spec does not permit that. If we use those lines, we end +@c up with truncated index entries that don't work. +@c @opindex +@var{first_page}[:@var{last_page}] +@c @opindex --pages=@var{first_page}[:@var{last_page}] +@opindex +@var{page_range} +@opindex --pages=@var{page_range} +Begin printing with page @var{first_page} and stop with @var{last_page}. +Missing @samp{:@var{last_page}} implies end of file. While estimating +the number of skipped pages each form feed in the input file results +in a new page. Page counting with and without @samp{+@var{first_page}} +is identical. By default, counting starts with the first page of input +file (not first page printed). Line numbering may be altered by @option{-N} +option. -@item --from=@var{unit} -@opindex --from -Auto-scales input numbers according to @var{unit}. See UNITS below. -The default is no scaling, meaning suffixes (e.g. @samp{M}, @samp{G}) will -trigger an error. +@item -@var{column} +@itemx --columns=@var{column} +@opindex -@var{column} +@opindex --columns +@cindex down columns +With each single @var{file}, produce @var{column} columns of output +(default is 1) and print columns down, unless @option{-a} is used. The +column width is automatically decreased as @var{column} increases; unless +you use the @option{-W/-w} option to increase @var{page_width} as well. +This option might well cause some lines to be truncated. The number of +lines in the columns on each page are balanced. The options @option{-e} +and @option{-i} are on for multiple text-column output. Together with +@option{-J} option column alignment and line truncation is turned off. +Lines of full length are joined in a free field format and @option{-S} +option may set field separators. @option{-@var{column}} may not be used +with @option{-m} option. -@item --from-unit=@var{n} -@opindex --from-unit -Specify the input unit size (instead of the default 1). Use this option when -the input numbers represent other units (e.g. if the input number @samp{10} -represents 10 units of 512 bytes, use @samp{--from=unit=512}). +@item -a +@itemx --across +@opindex -a +@opindex --across +@cindex across columns +With each single @var{file}, print columns across rather than down. The +@option{-@var{column}} option must be given with @var{column} greater than one. +If a line is too long to fit in a column, it is truncated. -@item --grouping -@opindex --grouping -Group digits in output numbers according to the current locale's grouping rules -(e.g @emph{Thousands Separator} character, commonly @samp{.} (dot) or @samp{,} -comma). This option has no effect in @samp{POSIX/C} locale. +@item -c +@itemx --show-control-chars +@opindex -c +@opindex --show-control-chars +Print control characters using hat notation (e.g., @samp{^G}); print +other nonprinting characters in octal backslash notation. By default, +nonprinting characters are not changed. -@item --header[=@var{n}] -@opindex --header -@opindex --header=N -Print the first @var{n} (default: 1) lines without any conversion. +@item -d +@itemx --double-space +@opindex -d +@opindex --double-space +@cindex double spacing +Double space the output. -@item --invalid=@var{mode} -@opindex --invalid -The default action on input errors is to exit immediately with status code 2. -@option{--invalid=@samp{abort}} explicitly specifies this default mode. -With a @var{mode} of @samp{fail}, print a warning for @emph{each} conversion -error, and exit with status 2. With a @var{mode} of @samp{warn}, exit with -status 0, even in the presence of conversion errors, and with a @var{mode} of -@samp{ignore} do not even print diagnostics. +@item -D @var{format} +@itemx --date-format=@var{format} +@cindex time formats +@cindex formatting times +Format header dates using @var{format}, using the same conventions as +for the command @samp{date +@var{format}}. @xref{date invocation}. +Except for directives, which start with +@samp{%}, characters in @var{format} are printed unchanged. You can use +this option to specify an arbitrary string in place of the header date, +e.g., @option{--date-format="Monday morning"}. -@item --padding=@var{n} -@opindex --padding -Pad the output numbers to @var{n} characters, by adding spaces. If @var{n} is -a positive number, numbers will be right-aligned. If @var{n} is a negative -number, numbers will be left-aligned. By default, numbers are automatically -aligned based on the input line's width (only with the default delimiter). +@vindex POSIXLY_CORRECT +@vindex LC_TIME +The default date format is @samp{%Y-%m-%d %H:%M} (for example, +@samp{2001-12-04 23:59}); +but if the @env{POSIXLY_CORRECT} environment variable is set +and the @env{LC_TIME} locale category specifies the POSIX +locale, the default is @samp{%b %e %H:%M %Y} (for example, +@samp{Dec@ @ 4 23:59 2001}. -@item --round=@var{method} -@opindex --round -@opindex --round=up -@opindex --round=down -@opindex --round=from-zero -@opindex --round=towards-zero -@opindex --round=nearest -When converting number representations, round the number according to -@var{method}, which can be @samp{up}, @samp{down}, -@samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}. +@vindex TZ +Time stamps are listed according to the time zone rules specified by +the @env{TZ} environment variable, or by the system default rules if +@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone +with @env{TZ}, libc, The GNU C Library Reference Manual}. -@item --suffix=@var{suffix} -@opindex --suffix -Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in -input numbers. +@item -e[@var{in-tabchar}[@var{in-tabwidth}]] +@itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]] +@opindex -e +@opindex --expand-tabs +@cindex input tabs +Expand @var{tab}s to spaces on input. Optional argument @var{in-tabchar} is +the input tab character (default is the TAB character). Second optional +argument @var{in-tabwidth} is the input tab character's width (default +is 8). -@item --to=@var{unit} -@opindex --to -Auto-scales output numbers according to @var{unit}. See @emph{Units} below. -The default is no scaling, meaning all the digits of the number are printed. +@item -f +@itemx -F +@itemx --form-feed +@opindex -F +@opindex -f +@opindex --form-feed +Use a form feed instead of newlines to separate output pages. This does +not alter the default page length of 66 lines. -@item --to-unit=@var{n} -@opindex --to-unit -Specify the output unit size (instead of the default 1). Use this option when -the output numbers represent other units (e.g. to represent @samp{4,000,000} -bytes in blocks of 1KB, use @samp{--to=si --to=units=1000}). +@item -h @var{header} +@itemx --header=@var{header} +@opindex -h +@opindex --header +Replace the file name in the header with the centered string @var{header}. +When using the shell, @var{header} should be quoted and should be +separated from @option{-h} by a space. -@end table +@item -i[@var{out-tabchar}[@var{out-tabwidth}]] +@itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]] +@opindex -i +@opindex --output-tabs +@cindex output tabs +Replace spaces with @var{tab}s on output. Optional argument @var{out-tabchar} +is the output tab character (default is the TAB character). Second optional +argument @var{out-tabwidth} is the output tab character's width (default +is 8). -@subsection Possible @var{unit}s: - -The following are the possible @var{unit} options with @option{--from=UNITS} and -@option{--to=UNITS}: - -@table @var - -@item none -No scaling is performed. For input numbers, no suffixes are accepted, and any -trailing characters following the number will trigger an error. For output -numbers, all digits of the numbers will be printed. - -@item si -Auto-scale numbers according to the @emph{International System of Units (SI)} -standard. -For input numbers, accept one of the following suffixes. -For output numbers, values larger than 1000 will be rounded, and printed with -one of the following suffixes: - -@example -@samp{K} => @math{1000^1 = 10^3} (Kilo) -@samp{M} => @math{1000^2 = 10^6} (Mega) -@samp{G} => @math{1000^3 = 10^9} (Giga) -@samp{T} => @math{1000^4 = 10^{12}} (Tera) -@samp{P} => @math{1000^5 = 10^{15}} (Peta) -@samp{E} => @math{1000^6 = 10^{18}} (Exa) -@samp{Z} => @math{1000^7 = 10^{21}} (Zetta) -@samp{Y} => @math{1000^8 = 10^{24}} (Yotta) -@end example - -@item iec -Auto-scale numbers according to the @emph{International Electrotechnical -Commission (IEC)} standard. -For input numbers, accept one of the following suffixes. -For output numbers, values larger than 1024 will be rounded, and printed with -one of the following suffixes: - -@example -@samp{K} => @math{1024^1 = 2^{10}} (Kibi) -@samp{M} => @math{1024^2 = 2^{20}} (Mebi) -@samp{G} => @math{1024^3 = 2^{30}} (Gibi) -@samp{T} => @math{1024^4 = 2^{40}} (Tebi) -@samp{P} => @math{1024^5 = 2^{50}} (Pebi) -@samp{E} => @math{1024^6 = 2^{60}} (Exbi) -@samp{Z} => @math{1024^7 = 2^{70}} (Zebi) -@samp{Y} => @math{1024^8 = 2^{80}} (Yobi) -@end example - -The @option{iec} option uses a single letter suffix (e.g. @samp{G}), which is -not fully standard, as the @emph{iec} standard recommends a two-letter symbol -(e.g @samp{Gi}) - but in practice, this method common. Compare with -the @option{iec-i} option. - -@item iec-i -Auto-scale numbers according to the @emph{International Electrotechnical -Commission (IEC)} standard. -For input numbers, accept one of the following suffixes. -For output numbers, values larger than 1024 will be rounded, and printed with -one of the following suffixes: - -@example -@samp{Ki} => @math{1024^1 = 2^{10}} (Kibi) -@samp{Mi} => @math{1024^2 = 2^{20}} (Mebi) -@samp{Gi} => @math{1024^3 = 2^{30}} (Gibi) -@samp{Ti} => @math{1024^4 = 2^{40}} (Tebi) -@samp{Pi} => @math{1024^5 = 2^{50}} (Pebi) -@samp{Ei} => @math{1024^6 = 2^{60}} (Exbi) -@samp{Zi} => @math{1024^7 = 2^{70}} (Zebi) -@samp{Yi} => @math{1024^8 = 2^{80}} (Yobi) -@end example - -The @option{iec-i} option uses a two-letter suffix symbol (e.g. @samp{Gi}), -as the @emph{iec} standard recommends, but this is not always common in -practice. Compare with the @option{iec} option. - -@item auto -@samp{auto} can only be used with @option{--from}. With this method, numbers -with @samp{K},@samp{M},@samp{G},@samp{T},@samp{P},@samp{E},@samp{Z},@samp{Y} -suffixes are interpreted as @emph{SI} values, and numbers with @samp{Ki}, -@samp{Mi},@samp{Gi},@samp{Ti},@samp{Pi},@samp{Ei},@samp{Zi},@samp{Yi} suffixes -are interpreted as @emph{IEC} values. - -@end table - -@subsection Examples of using @command{numfmt} - -Converting a single number from/to @emph{human} representation: -@example -$ numfmt --to=si 500000 -500K - -$ numfmt --to=iec 500000 -489K - -$ numfmt --to=iec-i 500000 -489Ki - -$ numfmt --from=si 1M -1000000 - -$ numfmt --from=iec 1M -1048576 - -# with '--from=auto', M=Mega, Mi=Mebi -$ numfmt --from=auto 1M -1000000 -$ numfmt --from=auto 1Mi -1048576 -@end example - -Converting from @samp{SI} to @samp{IEC} scales (e.g. when a harddisk capacity is -advertised as @samp{1TB}, while checking the drive's capacity gives lower -values): - -@example -$ numfmt --from=si --to=iec 1T -932G -@end example - - -Converting a single field from an input file / piped input (these contrived -examples are for demonstration purposes only, as both @command{ls} and -@command{df} support the @option{--human-readable} option to -output sizes in human-readable format): - -@example -# Third field (file size) will be shown in SI representation -$ ls -log | numfmt --field 3 --header --to=si | head -n4 --rw-r--r-- 1 94K Aug 23 2011 ABOUT-NLS --rw-r--r-- 1 3.7K Jan 7 16:15 AUTHORS --rw-r--r-- 1 36K Jun 1 2011 COPYING --rw-r--r-- 1 0 Jan 7 15:15 ChangeLog - -# Second field (size) will be shown in IEC representation -$ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4 -File system 1B-blocks Used Available Use% Mounted on -rootfs 132G 104741408 26554036 80% / -tmpfs 794M 7580 804960 1% /run/shm -/dev/sdb1 694G 651424756 46074696 94% /home -@end example - - -Output can be tweaked using @option{--padding} or @option{--format}: - -@example -# Pad to 10 characters, right-aligned -$ du -s * | numfmt --to=si --padding=10 - 2.5K config.log - 108 config.status - 1.7K configure - 20 configure.ac - -# Pad to 10 characters, left-aligned -$ du -s * | numfmt --to=si --padding=-10 -2.5K config.log -108 config.status -1.7K configure -20 configure.ac - -# Pad to 10 characters, left-aligned, using 'format' -$ du -s * | numfmt --to=si --format="%10f" - 2.5K config.log - 108 config.status - 1.7K configure - 20 configure.ac - -# Pad to 10 characters, left-aligned, using 'format' -$ du -s * | numfmt --to=si --padding="%-10f" -2.5K config.log -108 config.status -1.7K configure -20 configure.ac -@end example - -With locales that support grouping digits, using @option{--grouping} or -@option{--format} enables grouping. In @samp{POSIX} locale, grouping is -silently ignored: - -@example -$ LC_ALL=C numfmt --from=iec --grouping 2G -2147483648 - -$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G -2,147,483,648 - -$ LC_ALL=ta_IN numfmt --from=iec --grouping 2G -2,14,74,83,648 - -$ LC_ALL=C ./src/numfmt --from=iec --format="==%'15f==" 2G -== 2147483648== - -$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'15f==" 2G -== 2,147,483,648== - -$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'-15f==" 2G -==2,147,483,648 == - -$ LC_ALL=ta_IN ./src/numfmt --from=iec --format="==%'15f==" 2G -== 2,14,74,83,648== -@end example - -@node pr invocation -@section @command{pr}: Paginate or columnate files for printing - -@pindex pr -@cindex printing, preparing files for -@cindex multicolumn output, generating -@cindex merging files in parallel - -@command{pr} writes each @var{file} (@samp{-} means standard input), or -standard input if none are given, to standard output, paginating and -optionally outputting in multicolumn format; optionally merges all -@var{file}s, printing all in parallel, one per column. Synopsis: - -@example -pr [@var{option}]@dots{} [@var{file}]@dots{} -@end example - -@vindex LC_MESSAGES -By default, a 5-line header is printed at each page: two blank lines; -a line with the date, the file name, and the page count; and two more -blank lines. A footer of five blank lines is also printed. -The default @var{page_length} is 66 -lines. The default number of text lines is therefore 56. -The text line of the header takes the form -@samp{@var{date} @var{string} @var{page}}, with spaces inserted around -@var{string} so that the line takes up the full @var{page_width}. Here, -@var{date} is the date (see the @option{-D} or @option{--date-format} -option for details), @var{string} is the centered header string, and -@var{page} identifies the page number. The @env{LC_MESSAGES} locale -category affects the spelling of @var{page}; in the default C locale, it -is @samp{Page @var{number}} where @var{number} is the decimal page -number. - -Form feeds in the input cause page breaks in the output. Multiple form -feeds produce empty pages. - -Columns are of equal width, separated by an optional string (default -is @samp{space}). For multicolumn output, lines will always be truncated to -@var{page_width} (default 72), unless you use the @option{-J} option. -For single -column output no line truncation occurs by default. Use @option{-W} option to -truncate lines in that case. - -The program accepts the following options. Also see @ref{Common options}. - -@table @samp - -@item +@var{first_page}[:@var{last_page}] -@itemx --pages=@var{first_page}[:@var{last_page}] -@c The two following @opindex lines evoke warnings because they contain ':' -@c The 'info' spec does not permit that. If we use those lines, we end -@c up with truncated index entries that don't work. -@c @opindex +@var{first_page}[:@var{last_page}] -@c @opindex --pages=@var{first_page}[:@var{last_page}] -@opindex +@var{page_range} -@opindex --pages=@var{page_range} -Begin printing with page @var{first_page} and stop with @var{last_page}. -Missing @samp{:@var{last_page}} implies end of file. While estimating -the number of skipped pages each form feed in the input file results -in a new page. Page counting with and without @samp{+@var{first_page}} -is identical. By default, counting starts with the first page of input -file (not first page printed). Line numbering may be altered by @option{-N} -option. - -@item -@var{column} -@itemx --columns=@var{column} -@opindex -@var{column} -@opindex --columns -@cindex down columns -With each single @var{file}, produce @var{column} columns of output -(default is 1) and print columns down, unless @option{-a} is used. The -column width is automatically decreased as @var{column} increases; unless -you use the @option{-W/-w} option to increase @var{page_width} as well. -This option might well cause some lines to be truncated. The number of -lines in the columns on each page are balanced. The options @option{-e} -and @option{-i} are on for multiple text-column output. Together with -@option{-J} option column alignment and line truncation is turned off. -Lines of full length are joined in a free field format and @option{-S} -option may set field separators. @option{-@var{column}} may not be used -with @option{-m} option. - -@item -a -@itemx --across -@opindex -a -@opindex --across -@cindex across columns -With each single @var{file}, print columns across rather than down. The -@option{-@var{column}} option must be given with @var{column} greater than one. -If a line is too long to fit in a column, it is truncated. - -@item -c -@itemx --show-control-chars -@opindex -c -@opindex --show-control-chars -Print control characters using hat notation (e.g., @samp{^G}); print -other nonprinting characters in octal backslash notation. By default, -nonprinting characters are not changed. - -@item -d -@itemx --double-space -@opindex -d -@opindex --double-space -@cindex double spacing -Double space the output. - -@item -D @var{format} -@itemx --date-format=@var{format} -@cindex time formats -@cindex formatting times -Format header dates using @var{format}, using the same conventions as -for the command @samp{date +@var{format}}. @xref{date invocation}. -Except for directives, which start with -@samp{%}, characters in @var{format} are printed unchanged. You can use -this option to specify an arbitrary string in place of the header date, -e.g., @option{--date-format="Monday morning"}. - -@vindex POSIXLY_CORRECT -@vindex LC_TIME -The default date format is @samp{%Y-%m-%d %H:%M} (for example, -@samp{2001-12-04 23:59}); -but if the @env{POSIXLY_CORRECT} environment variable is set -and the @env{LC_TIME} locale category specifies the POSIX -locale, the default is @samp{%b %e %H:%M %Y} (for example, -@samp{Dec@ @ 4 23:59 2001}. - -@vindex TZ -Time stamps are listed according to the time zone rules specified by -the @env{TZ} environment variable, or by the system default rules if -@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone -with @env{TZ}, libc, The GNU C Library Reference Manual}. - -@item -e[@var{in-tabchar}[@var{in-tabwidth}]] -@itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]] -@opindex -e -@opindex --expand-tabs -@cindex input tabs -Expand @var{tab}s to spaces on input. Optional argument @var{in-tabchar} is -the input tab character (default is the TAB character). Second optional -argument @var{in-tabwidth} is the input tab character's width (default -is 8). - -@item -f -@itemx -F -@itemx --form-feed -@opindex -F -@opindex -f -@opindex --form-feed -Use a form feed instead of newlines to separate output pages. This does -not alter the default page length of 66 lines. - -@item -h @var{header} -@itemx --header=@var{header} -@opindex -h -@opindex --header -Replace the file name in the header with the centered string @var{header}. -When using the shell, @var{header} should be quoted and should be -separated from @option{-h} by a space. - -@item -i[@var{out-tabchar}[@var{out-tabwidth}]] -@itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]] -@opindex -i -@opindex --output-tabs -@cindex output tabs -Replace spaces with @var{tab}s on output. Optional argument @var{out-tabchar} -is the output tab character (default is the TAB character). Second optional -argument @var{out-tabwidth} is the output tab character's width (default -is 8). - -@item -J -@itemx --join-lines -@opindex -J -@opindex --join-lines -Merge lines of full length. Used together with the column options -@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off -@option{-W/-w} line truncation; -no column alignment used; may be used with -@option{--sep-string[=@var{string}]}. @option{-J} has been introduced -(together with @option{-W} and @option{--sep-string}) -to disentangle the old (POSIX-compliant) options @option{-w} and -@option{-s} along with the three column options. +@item -J +@itemx --join-lines +@opindex -J +@opindex --join-lines +Merge lines of full length. Used together with the column options +@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off +@option{-W/-w} line truncation; +no column alignment used; may be used with +@option{--sep-string[=@var{string}]}. @option{-J} has been introduced +(together with @option{-W} and @option{--sep-string}) +to disentangle the old (POSIX-compliant) options @option{-w} and +@option{-s} along with the three column options. @item -l @var{page_length} @@ -16865,301 +16542,625 @@ the exit status of @var{command} otherwise @end display -@node timeout invocation -@section @command{timeout}: Run a command with a time limit +@node timeout invocation +@section @command{timeout}: Run a command with a time limit + +@pindex timeout +@cindex time limit +@cindex run commands with bounded time + +@command{timeout} runs the given @var{command} and kills it if it is +still running after the specified time interval. Synopsis: + +@example +timeout [@var{option}] @var{duration} @var{command} [@var{arg}]@dots{} +@end example + +@var{command} must not be a special built-in utility (@pxref{Special +built-in utilities}). + +The program accepts the following options. Also see @ref{Common options}. +Options must precede operands. + +@table @samp +@item --preserve-status +@opindex --preserve-status +Return the exit status of the managed @var{command} on timeout, rather than +a specific exit status indicating a timeout. This is useful if the +managed @var{command} supports running for an indeterminate amount of time. + +@item --foreground +@opindex --foreground +Don't create a separate background program group, so that +the managed @var{command} can use the foreground TTY normally. +This is needed to support timing out commands not started +directly from an interactive shell, in two situations. +@enumerate +@item +@var{command} is interactive and needs to read from the terminal for example +@item +the user wants to support sending signals directly to @var{command} +from the terminal (like Ctrl-C for example) +@end enumerate + +Note in this mode of operation, any children of @var{command} +will not be timed out. + +@item -k @var{duration} +@itemx --kill-after=@var{duration} +@opindex -k +@opindex --kill-after +Ensure the monitored @var{command} is killed by also sending a @samp{KILL} +signal, after the specified @var{duration}. Without this option, if the +selected signal proves not to be fatal, @command{timeout} does not kill +the @var{command}. + +@item -s @var{signal} +@itemx --signal=@var{signal} +@opindex -s +@opindex --signal +Send this @var{signal} to @var{command} on timeout, rather than the +default @samp{TERM} signal. @var{signal} may be a name like @samp{HUP} +or a number. @xref{Signal specifications}. +@end table + +@cindex time units +@var{duration} is a floating point number followed by an optional unit: +@display +@samp{s} for seconds (the default) +@samp{m} for minutes +@samp{h} for hours +@samp{d} for days +@end display +A duration of 0 disables the associated timeout. +Note that the actual timeout duration is dependent on system conditions, +which should be especially considered when specifying sub-second timeouts. + +@cindex exit status of @command{timeout} +Exit status: + +@display +124 if @var{command} times out +125 if @command{timeout} itself fails +126 if @var{command} is found but cannot be invoked +127 if @var{command} cannot be found +137 if @var{command} is sent the KILL(9) signal (128+9) +the exit status of @var{command} otherwise +@end display + + +@node Process control +@chapter Process control + +@cindex processes, commands for controlling +@cindex commands for controlling processes + +@menu +* kill invocation:: Sending a signal to processes. +@end menu + + +@node kill invocation +@section @command{kill}: Send a signal to processes + +@pindex kill +@cindex send a signal to processes + +The @command{kill} command sends a signal to processes, causing them +to terminate or otherwise act upon receiving the signal in some way. +Alternatively, it lists information about signals. Synopses: + +@example +kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{} +kill [-l | --list | -t | --table] [@var{signal}]@dots{} +@end example + +@mayConflictWithShellBuiltIn{kill} + +The first form of the @command{kill} command sends a signal to all +@var{pid} arguments. The default signal to send if none is specified +is @samp{TERM}@. The special signal number @samp{0} does not denote a +valid signal, but can be used to test whether the @var{pid} arguments +specify processes to which a signal could be sent. + +If @var{pid} is positive, the signal is sent to the process with the +process ID @var{pid}. If @var{pid} is zero, the signal is sent to all +processes in the process group of the current process. If @var{pid} +is @minus{}1, the signal is sent to all processes for which the user has +permission to send a signal. If @var{pid} is less than @minus{}1, the signal +is sent to all processes in the process group that equals the absolute +value of @var{pid}. + +If @var{pid} is not positive, a system-dependent set of system +processes is excluded from the list of processes to which the signal +is sent. + +If a negative @var{pid} argument is desired as the first one, it +should be preceded by @option{--}. However, as a common extension to +POSIX, @option{--} is not required with @samp{kill +-@var{signal} -@var{pid}}. The following commands are equivalent: + +@example +kill -15 -1 +kill -TERM -1 +kill -s TERM -- -1 +kill -- -1 +@end example + +The first form of the @command{kill} command succeeds if every @var{pid} +argument specifies at least one process that the signal was sent to. + +The second form of the @command{kill} command lists signal information. +Either the @option{-l} or @option{--list} option, or the @option{-t} +or @option{--table} option must be specified. Without any +@var{signal} argument, all supported signals are listed. The output +of @option{-l} or @option{--list} is a list of the signal names, one +per line; if @var{signal} is already a name, the signal number is +printed instead. The output of @option{-t} or @option{--table} is a +table of signal numbers, names, and descriptions. This form of the +@command{kill} command succeeds if all @var{signal} arguments are valid +and if there is no output error. + +The @command{kill} command also supports the @option{--help} and +@option{--version} options. @xref{Common options}. + +A @var{signal} may be a signal name like @samp{HUP}, or a signal +number like @samp{1}, or an exit status of a process terminated by the +signal. A signal name can be given in canonical form or prefixed by +@samp{SIG}@. The case of the letters is ignored, except for the +@option{-@var{signal}} option which must use upper case to avoid +ambiguity with lower case option letters. +@xref{Signal specifications}, for a list of supported +signal names and numbers. + +@node Delaying +@chapter Delaying + +@cindex delaying commands +@cindex commands for delaying + +@c Perhaps @command{wait} or other commands should be described here also? + +@menu +* sleep invocation:: Delay for a specified time. +@end menu + + +@node sleep invocation +@section @command{sleep}: Delay for a specified time + +@pindex sleep +@cindex delay for a specified time + +@command{sleep} pauses for an amount of time specified by the sum of +the values of the command line arguments. +Synopsis: + +@example +sleep @var{number}[smhd]@dots{} +@end example + +@cindex time units +Each argument is a number followed by an optional unit; the default +is seconds. The units are: + +@table @samp +@item s +seconds +@item m +minutes +@item h +hours +@item d +days +@end table + +Historical implementations of @command{sleep} have required that +@var{number} be an integer, and only accepted a single argument +without a suffix. However, GNU @command{sleep} accepts +arbitrary floating point numbers. @xref{Floating point}. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@c sleep is a shell built-in at least with Solaris 11's /bin/sh +@mayConflictWithShellBuiltIn{sleep} + +@exitstatus + + +@node Numeric operations +@chapter Numeric operations + +@cindex numeric operations +These programs do numerically-related operations. + +@menu +* factor invocation:: Show factors of numbers. +* numfmt invocation:: Reformat numbers. +* seq invocation:: Print sequences of numbers. +@end menu + + +@node factor invocation +@section @command{factor}: Print prime factors + +@pindex factor +@cindex prime factors + +@command{factor} prints prime factors. Synopses: + +@example +factor [@var{number}]@dots{} +factor @var{option} +@end example + +If no @var{number} is specified on the command line, @command{factor} reads +numbers from standard input, delimited by newlines, tabs, or spaces. + +The @command{factor} command supports only a small number of options: + +@table @samp +@item --help +Print a short help on standard output, then exit without further +processing. -@pindex timeout -@cindex time limit -@cindex run commands with bounded time +@item --version +Print the program version on standard output, then exit without further +processing. +@end table -@command{timeout} runs the given @var{command} and kills it if it is -still running after the specified time interval. Synopsis: +Factoring the product of the eighth and ninth Mersenne primes +takes about 30 milliseconds of CPU time on a 2.2 GHz Athlon. @example -timeout [@var{option}] @var{duration} @var{command} [@var{arg}]@dots{} +M8=$(echo 2^31-1|bc) +M9=$(echo 2^61-1|bc) +n=$(echo "$M8 * $M9" | bc) +/usr/bin/time -f %U factor $n +4951760154835678088235319297: 2147483647 2305843009213693951 +0.03 @end example -@var{command} must not be a special built-in utility (@pxref{Special -built-in utilities}). +Similarly, factoring the eighth Fermat number @math{2^{256}+1} takes +about 20 seconds on the same machine. -The program accepts the following options. Also see @ref{Common options}. -Options must precede operands. +Factoring large numbers is, in general, hard. The Pollard Rho +algorithm used by @command{factor} is particularly effective for +numbers with relatively small factors. If you wish to factor large +numbers which do not have small factors (for example, numbers which +are the product of two large primes), other methods are far better. -@table @samp -@item --preserve-status -@opindex --preserve-status -Return the exit status of the managed @var{command} on timeout, rather than -a specific exit status indicating a timeout. This is useful if the -managed @var{command} supports running for an indeterminate amount of time. +If @command{factor} is built without using GNU MP, only +single-precision arithmetic is available, and so large numbers +(typically @math{2^{64}} and above) will not be supported. The single-precision +code uses an algorithm which is designed for factoring smaller +numbers. -@item --foreground -@opindex --foreground -Don't create a separate background program group, so that -the managed @var{command} can use the foreground TTY normally. -This is needed to support timing out commands not started -directly from an interactive shell, in two situations. -@enumerate -@item -@var{command} is interactive and needs to read from the terminal for example -@item -the user wants to support sending signals directly to @var{command} -from the terminal (like Ctrl-C for example) -@end enumerate +@exitstatus -Note in this mode of operation, any children of @var{command} -will not be timed out. -@item -k @var{duration} -@itemx --kill-after=@var{duration} -@opindex -k -@opindex --kill-after -Ensure the monitored @var{command} is killed by also sending a @samp{KILL} -signal, after the specified @var{duration}. Without this option, if the -selected signal proves not to be fatal, @command{timeout} does not kill -the @var{command}. +@node numfmt invocation +@section @command{numfmt}: Reformat numbers -@item -s @var{signal} -@itemx --signal=@var{signal} -@opindex -s -@opindex --signal -Send this @var{signal} to @var{command} on timeout, rather than the -default @samp{TERM} signal. @var{signal} may be a name like @samp{HUP} -or a number. @xref{Signal specifications}. -@end table +@pindex numfmt -@cindex time units -@var{duration} is a floating point number followed by an optional unit: -@display -@samp{s} for seconds (the default) -@samp{m} for minutes -@samp{h} for hours -@samp{d} for days -@end display -A duration of 0 disables the associated timeout. -Note that the actual timeout duration is dependent on system conditions, -which should be especially considered when specifying sub-second timeouts. +@command{numfmt} reads numbers in various representations and reformats them +as requested. The most common usage is converting numbers to/from @emph{human} +representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}). -@cindex exit status of @command{timeout} -Exit status: +@example +numfmt [@var{option}]@dots{} [@var{number}] +@end example -@display -124 if @var{command} times out -125 if @command{timeout} itself fails -126 if @var{command} is found but cannot be invoked -127 if @var{command} cannot be found -137 if @var{command} is sent the KILL(9) signal (128+9) -the exit status of @var{command} otherwise -@end display +@command{numfmt} converts each @var{number} on the command-line according to the +specified options (see below). If no @var{number}s are given, it reads numbers +from standard input. @command{numfmt} can optionally extract numbers from +specific columns, maintaining proper line padding and alignment. +@exitstatus -@node Process control -@chapter Process control +See @option{--invalid} for additional information regarding exit status. -@cindex processes, commands for controlling -@cindex commands for controlling processes +@subsection General options -@menu -* kill invocation:: Sending a signal to processes. -@end menu +The program accepts the following options. Also see @ref{Common options}. +@table @samp -@node kill invocation -@section @command{kill}: Send a signal to processes +@item --debug +@opindex --debug +Print (to standard error) warning messages about possible erroneous usage. -@pindex kill -@cindex send a signal to processes +@item -d @var{d} +@itemx --delimiter=@var{d} +@opindex -d +@opindex --delimiter +Use the character @var{d} as input field separator (default: whitespace). +@emph{Note}: Using non-default delimiter turns off automatic padding. -The @command{kill} command sends a signal to processes, causing them -to terminate or otherwise act upon receiving the signal in some way. -Alternatively, it lists information about signals. Synopses: +@item --field=@var{n} +@opindex --field +Convert the number in input field @var{n} (default: 1). -@example -kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{} -kill [-l | --list | -t | --table] [@var{signal}]@dots{} -@end example +@item --format=@var{format} +@opindex --format +Use printf-style floating FORMAT string. The @var{format} string must contain +one @samp{%f} directive, optionally with @samp{'}, @samp{-}, @samp{0}, or width +modifiers. The @samp{'} modifier will enable @option{--grouping}, the @samp{-} +modifier will enable left-aligned @option{--padding} and the width modifier will +enable right-aligned @option{--padding}. The @samp{0} width modifier +(without the @samp{-} modifier) will generate leading zeros on the number, +up to the specified width. -@mayConflictWithShellBuiltIn{kill} +@item --from=@var{unit} +@opindex --from +Auto-scales input numbers according to @var{unit}. See UNITS below. +The default is no scaling, meaning suffixes (e.g. @samp{M}, @samp{G}) will +trigger an error. -The first form of the @command{kill} command sends a signal to all -@var{pid} arguments. The default signal to send if none is specified -is @samp{TERM}@. The special signal number @samp{0} does not denote a -valid signal, but can be used to test whether the @var{pid} arguments -specify processes to which a signal could be sent. +@item --from-unit=@var{n} +@opindex --from-unit +Specify the input unit size (instead of the default 1). Use this option when +the input numbers represent other units (e.g. if the input number @samp{10} +represents 10 units of 512 bytes, use @samp{--from=unit=512}). -If @var{pid} is positive, the signal is sent to the process with the -process ID @var{pid}. If @var{pid} is zero, the signal is sent to all -processes in the process group of the current process. If @var{pid} -is @minus{}1, the signal is sent to all processes for which the user has -permission to send a signal. If @var{pid} is less than @minus{}1, the signal -is sent to all processes in the process group that equals the absolute -value of @var{pid}. +@item --grouping +@opindex --grouping +Group digits in output numbers according to the current locale's grouping rules +(e.g @emph{Thousands Separator} character, commonly @samp{.} (dot) or @samp{,} +comma). This option has no effect in @samp{POSIX/C} locale. -If @var{pid} is not positive, a system-dependent set of system -processes is excluded from the list of processes to which the signal -is sent. +@item --header[=@var{n}] +@opindex --header +@opindex --header=N +Print the first @var{n} (default: 1) lines without any conversion. -If a negative @var{pid} argument is desired as the first one, it -should be preceded by @option{--}. However, as a common extension to -POSIX, @option{--} is not required with @samp{kill --@var{signal} -@var{pid}}. The following commands are equivalent: +@item --invalid=@var{mode} +@opindex --invalid +The default action on input errors is to exit immediately with status code 2. +@option{--invalid=@samp{abort}} explicitly specifies this default mode. +With a @var{mode} of @samp{fail}, print a warning for @emph{each} conversion +error, and exit with status 2. With a @var{mode} of @samp{warn}, exit with +status 0, even in the presence of conversion errors, and with a @var{mode} of +@samp{ignore} do not even print diagnostics. -@example -kill -15 -1 -kill -TERM -1 -kill -s TERM -- -1 -kill -- -1 -@end example +@item --padding=@var{n} +@opindex --padding +Pad the output numbers to @var{n} characters, by adding spaces. If @var{n} is +a positive number, numbers will be right-aligned. If @var{n} is a negative +number, numbers will be left-aligned. By default, numbers are automatically +aligned based on the input line's width (only with the default delimiter). -The first form of the @command{kill} command succeeds if every @var{pid} -argument specifies at least one process that the signal was sent to. +@item --round=@var{method} +@opindex --round +@opindex --round=up +@opindex --round=down +@opindex --round=from-zero +@opindex --round=towards-zero +@opindex --round=nearest +When converting number representations, round the number according to +@var{method}, which can be @samp{up}, @samp{down}, +@samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}. -The second form of the @command{kill} command lists signal information. -Either the @option{-l} or @option{--list} option, or the @option{-t} -or @option{--table} option must be specified. Without any -@var{signal} argument, all supported signals are listed. The output -of @option{-l} or @option{--list} is a list of the signal names, one -per line; if @var{signal} is already a name, the signal number is -printed instead. The output of @option{-t} or @option{--table} is a -table of signal numbers, names, and descriptions. This form of the -@command{kill} command succeeds if all @var{signal} arguments are valid -and if there is no output error. +@item --suffix=@var{suffix} +@opindex --suffix +Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in +input numbers. + +@item --to=@var{unit} +@opindex --to +Auto-scales output numbers according to @var{unit}. See @emph{Units} below. +The default is no scaling, meaning all the digits of the number are printed. + +@item --to-unit=@var{n} +@opindex --to-unit +Specify the output unit size (instead of the default 1). Use this option when +the output numbers represent other units (e.g. to represent @samp{4,000,000} +bytes in blocks of 1KB, use @samp{--to=si --to=units=1000}). + +@end table -The @command{kill} command also supports the @option{--help} and -@option{--version} options. @xref{Common options}. +@subsection Possible @var{unit}s: -A @var{signal} may be a signal name like @samp{HUP}, or a signal -number like @samp{1}, or an exit status of a process terminated by the -signal. A signal name can be given in canonical form or prefixed by -@samp{SIG}@. The case of the letters is ignored, except for the -@option{-@var{signal}} option which must use upper case to avoid -ambiguity with lower case option letters. -@xref{Signal specifications}, for a list of supported -signal names and numbers. +The following are the possible @var{unit} options with @option{--from=UNITS} and +@option{--to=UNITS}: -@node Delaying -@chapter Delaying +@table @var -@cindex delaying commands -@cindex commands for delaying +@item none +No scaling is performed. For input numbers, no suffixes are accepted, and any +trailing characters following the number will trigger an error. For output +numbers, all digits of the numbers will be printed. -@c Perhaps @command{wait} or other commands should be described here also? +@item si +Auto-scale numbers according to the @emph{International System of Units (SI)} +standard. +For input numbers, accept one of the following suffixes. +For output numbers, values larger than 1000 will be rounded, and printed with +one of the following suffixes: -@menu -* sleep invocation:: Delay for a specified time. -@end menu +@example +@samp{K} => @math{1000^1 = 10^3} (Kilo) +@samp{M} => @math{1000^2 = 10^6} (Mega) +@samp{G} => @math{1000^3 = 10^9} (Giga) +@samp{T} => @math{1000^4 = 10^{12}} (Tera) +@samp{P} => @math{1000^5 = 10^{15}} (Peta) +@samp{E} => @math{1000^6 = 10^{18}} (Exa) +@samp{Z} => @math{1000^7 = 10^{21}} (Zetta) +@samp{Y} => @math{1000^8 = 10^{24}} (Yotta) +@end example +@item iec +Auto-scale numbers according to the @emph{International Electrotechnical +Commission (IEC)} standard. +For input numbers, accept one of the following suffixes. +For output numbers, values larger than 1024 will be rounded, and printed with +one of the following suffixes: -@node sleep invocation -@section @command{sleep}: Delay for a specified time +@example +@samp{K} => @math{1024^1 = 2^{10}} (Kibi) +@samp{M} => @math{1024^2 = 2^{20}} (Mebi) +@samp{G} => @math{1024^3 = 2^{30}} (Gibi) +@samp{T} => @math{1024^4 = 2^{40}} (Tebi) +@samp{P} => @math{1024^5 = 2^{50}} (Pebi) +@samp{E} => @math{1024^6 = 2^{60}} (Exbi) +@samp{Z} => @math{1024^7 = 2^{70}} (Zebi) +@samp{Y} => @math{1024^8 = 2^{80}} (Yobi) +@end example -@pindex sleep -@cindex delay for a specified time +The @option{iec} option uses a single letter suffix (e.g. @samp{G}), which is +not fully standard, as the @emph{iec} standard recommends a two-letter symbol +(e.g @samp{Gi}) - but in practice, this method common. Compare with +the @option{iec-i} option. -@command{sleep} pauses for an amount of time specified by the sum of -the values of the command line arguments. -Synopsis: +@item iec-i +Auto-scale numbers according to the @emph{International Electrotechnical +Commission (IEC)} standard. +For input numbers, accept one of the following suffixes. +For output numbers, values larger than 1024 will be rounded, and printed with +one of the following suffixes: @example -sleep @var{number}[smhd]@dots{} +@samp{Ki} => @math{1024^1 = 2^{10}} (Kibi) +@samp{Mi} => @math{1024^2 = 2^{20}} (Mebi) +@samp{Gi} => @math{1024^3 = 2^{30}} (Gibi) +@samp{Ti} => @math{1024^4 = 2^{40}} (Tebi) +@samp{Pi} => @math{1024^5 = 2^{50}} (Pebi) +@samp{Ei} => @math{1024^6 = 2^{60}} (Exbi) +@samp{Zi} => @math{1024^7 = 2^{70}} (Zebi) +@samp{Yi} => @math{1024^8 = 2^{80}} (Yobi) @end example -@cindex time units -Each argument is a number followed by an optional unit; the default -is seconds. The units are: +The @option{iec-i} option uses a two-letter suffix symbol (e.g. @samp{Gi}), +as the @emph{iec} standard recommends, but this is not always common in +practice. Compare with the @option{iec} option. -@table @samp -@item s -seconds -@item m -minutes -@item h -hours -@item d -days -@end table +@item auto +@samp{auto} can only be used with @option{--from}. With this method, numbers +with @samp{K},@samp{M},@samp{G},@samp{T},@samp{P},@samp{E},@samp{Z},@samp{Y} +suffixes are interpreted as @emph{SI} values, and numbers with @samp{Ki}, +@samp{Mi},@samp{Gi},@samp{Ti},@samp{Pi},@samp{Ei},@samp{Zi},@samp{Yi} suffixes +are interpreted as @emph{IEC} values. -Historical implementations of @command{sleep} have required that -@var{number} be an integer, and only accepted a single argument -without a suffix. However, GNU @command{sleep} accepts -arbitrary floating point numbers. @xref{Floating point}. +@end table -The only options are @option{--help} and @option{--version}. @xref{Common -options}. +@subsection Examples of using @command{numfmt} -@c sleep is a shell built-in at least with Solaris 11's /bin/sh -@mayConflictWithShellBuiltIn{sleep} +Converting a single number from/to @emph{human} representation: +@example +$ numfmt --to=si 500000 +500K -@exitstatus +$ numfmt --to=iec 500000 +489K +$ numfmt --to=iec-i 500000 +489Ki -@node Numeric operations -@chapter Numeric operations +$ numfmt --from=si 1M +1000000 -@cindex numeric operations -These programs do numerically-related operations. +$ numfmt --from=iec 1M +1048576 -@menu -* factor invocation:: Show factors of numbers. -* seq invocation:: Print sequences of numbers. -@end menu +# with '--from=auto', M=Mega, Mi=Mebi +$ numfmt --from=auto 1M +1000000 +$ numfmt --from=auto 1Mi +1048576 +@end example +Converting from @samp{SI} to @samp{IEC} scales (e.g. when a harddisk capacity is +advertised as @samp{1TB}, while checking the drive's capacity gives lower +values): -@node factor invocation -@section @command{factor}: Print prime factors +@example +$ numfmt --from=si --to=iec 1T +932G +@end example -@pindex factor -@cindex prime factors -@command{factor} prints prime factors. Synopses: +Converting a single field from an input file / piped input (these contrived +examples are for demonstration purposes only, as both @command{ls} and +@command{df} support the @option{--human-readable} option to +output sizes in human-readable format): @example -factor [@var{number}]@dots{} -factor @var{option} +# Third field (file size) will be shown in SI representation +$ ls -log | numfmt --field 3 --header --to=si | head -n4 +-rw-r--r-- 1 94K Aug 23 2011 ABOUT-NLS +-rw-r--r-- 1 3.7K Jan 7 16:15 AUTHORS +-rw-r--r-- 1 36K Jun 1 2011 COPYING +-rw-r--r-- 1 0 Jan 7 15:15 ChangeLog + +# Second field (size) will be shown in IEC representation +$ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4 +File system 1B-blocks Used Available Use% Mounted on +rootfs 132G 104741408 26554036 80% / +tmpfs 794M 7580 804960 1% /run/shm +/dev/sdb1 694G 651424756 46074696 94% /home @end example -If no @var{number} is specified on the command line, @command{factor} reads -numbers from standard input, delimited by newlines, tabs, or spaces. -The @command{factor} command supports only a small number of options: +Output can be tweaked using @option{--padding} or @option{--format}: -@table @samp -@item --help -Print a short help on standard output, then exit without further -processing. +@example +# Pad to 10 characters, right-aligned +$ du -s * | numfmt --to=si --padding=10 + 2.5K config.log + 108 config.status + 1.7K configure + 20 configure.ac -@item --version -Print the program version on standard output, then exit without further -processing. -@end table +# Pad to 10 characters, left-aligned +$ du -s * | numfmt --to=si --padding=-10 +2.5K config.log +108 config.status +1.7K configure +20 configure.ac -Factoring the product of the eighth and ninth Mersenne primes -takes about 30 milliseconds of CPU time on a 2.2 GHz Athlon. +# Pad to 10 characters, left-aligned, using 'format' +$ du -s * | numfmt --to=si --format="%10f" + 2.5K config.log + 108 config.status + 1.7K configure + 20 configure.ac -@example -M8=$(echo 2^31-1|bc) -M9=$(echo 2^61-1|bc) -n=$(echo "$M8 * $M9" | bc) -/usr/bin/time -f %U factor $n -4951760154835678088235319297: 2147483647 2305843009213693951 -0.03 +# Pad to 10 characters, left-aligned, using 'format' +$ du -s * | numfmt --to=si --padding="%-10f" +2.5K config.log +108 config.status +1.7K configure +20 configure.ac @end example -Similarly, factoring the eighth Fermat number @math{2^{256}+1} takes -about 20 seconds on the same machine. +With locales that support grouping digits, using @option{--grouping} or +@option{--format} enables grouping. In @samp{POSIX} locale, grouping is +silently ignored: -Factoring large numbers is, in general, hard. The Pollard Rho -algorithm used by @command{factor} is particularly effective for -numbers with relatively small factors. If you wish to factor large -numbers which do not have small factors (for example, numbers which -are the product of two large primes), other methods are far better. +@example +$ LC_ALL=C numfmt --from=iec --grouping 2G +2147483648 -If @command{factor} is built without using GNU MP, only -single-precision arithmetic is available, and so large numbers -(typically @math{2^{64}} and above) will not be supported. The single-precision -code uses an algorithm which is designed for factoring smaller -numbers. +$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G +2,147,483,648 -@exitstatus +$ LC_ALL=ta_IN numfmt --from=iec --grouping 2G +2,14,74,83,648 + +$ LC_ALL=C ./src/numfmt --from=iec --format="==%'15f==" 2G +== 2147483648== + +$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'15f==" 2G +== 2,147,483,648== + +$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'-15f==" 2G +==2,147,483,648 == + +$ LC_ALL=ta_IN ./src/numfmt --from=iec --format="==%'15f==" 2G +== 2,14,74,83,648== +@end example @node seq invocation -- 2.47.2