On 01/21/2011 01:24 AM, Jim Meyering wrote: > My first reflex was to make sleep reject args like 0x... and inf.
My reflex was just the opposite: why reject a notation that might be useful? Several other programs (printf, seq, sort, tail, plus many other GNU programs) also use strtod or strtold. If 'sleep' is changed to reject hexadecimal and infinity, shouldn't they be changed too, for consistency? I expect it's better to leave these programs alone. Not only is this simpler, and a tiny bit cheaper at runtime, it's slightly less likely to break existing usage. Anyway, whatever we do, we should document it better. To start the ball rolling on that, I pushed the following change, which documents the existing behavior. We can change this if we change the behavior. >From df79069b2cfb8435e8b33693c9e03e8689b2659b Mon Sep 17 00:00:00 2001 From: Paul Eggert <egg...@cs.ucla.edu> Date: Fri, 21 Jan 2011 10:59:32 -0800 Subject: [PATCH] manual: document floating point better * doc/coreutils.texi (Floating point): New section. (od invocation, tail invocation, sort invocation, printf invocation): (sleep invocation, seq invocation): Refer and defer to it. See <http://lists.gnu.org/archive/html/bug-coreutils/2011-01/msg00031.html>. --- doc/coreutils.texi | 52 +++++++++++++++++++++++++++++++++++++++------------- 1 files changed, 39 insertions(+), 13 deletions(-) diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 8a1b3b6..926171c 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -217,6 +217,7 @@ Common Options * Exit status:: Indicating program success or failure * Backup options:: Backup options * Block size:: Block size +* Floating point:: Floating point number representation * Signal specifications:: Specifying signals * Disambiguating names and IDs:: chgrp and chown owner and group syntax * Random sources:: Sources of random data @@ -729,6 +730,7 @@ name. * Exit status:: Indicating program success or failure. * Backup options:: -b -S, in some programs. * Block size:: BLOCK_SIZE and --block-size, in some programs. +* Floating point:: Floating point number representation. * Signal specifications:: Specifying signals using the --signal option. * Disambiguating names and IDs:: chgrp and chown owner and group syntax * Random sources:: --random-source, in some programs. @@ -1011,6 +1013,34 @@ set. The @option{-h} or @option{--human-readable} option is equivalent to @option{--block-size=human-readable}. The @option{--si} option is equivalent to @option{--block-size=si}. +@node Floating point +@section Floating point numbers +@cindex floating point +@cindex IEEE floating point + +Commands that accept or produce floating point numbers employ the +floating point representation of the underlying system, and suffer +from rounding error, overflow, and similar floating-point issues. +Almost all modern systems use IEEE-754 floating point, and it is +typically portable to assume IEEE-754 behavior these days. IEEE-754 +has positive and negative infinity, distinguishes positive from +negative zero, and uses special values called NaNs to represent +invalid computations such as dividing zero by itself. For more +information, please see David Goldberg's paper +@uref{http://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every +Computer Scientist Should Know About Floating-Point Arithmetic}. + +@vindex LC_NUMERIC +Commands that accept floating point numbers as options, operands or +input use the standard C functions @code{strtod} and @code{strtold} to +convert from text to floating point numbers. These floating point +numbers therefore can use scientific notation like @code{1.0e-34} and +@code{-10e100}. Modern C implementations also accept hexadecimal +floating point numbers such as @code{-0x.ep-3}, which stands for +@minus{}14/16 times @math{2^-3}, which equals @minus{}0.109375. The +@env{LC_NUMERIC} locale determines the decimal-point character. +@xref{Parsing of Floats,,, libc, The GNU C Library Reference Manual}. + @node Signal specifications @section Signal specifications @cindex signals, specifying @@ -1880,7 +1910,7 @@ named character, ignoring high-order bit @item d signed decimal @item f -floating point +floating point (@pxref{Floating point}) @item o octal @item u @@ -2820,8 +2850,7 @@ During one iteration, every specified file is checked to see if it has changed size. Historical implementations of @command{tail} have required that @var{number} be an integer. However, GNU @command{tail} accepts -an arbitrary floating point number (using a period before any -fractional digits). +an arbitrary floating point number. @xref{Floating point}. When @command{tail} uses inotify, this polling-related option is ignored. @itemx --pid=@var{pid} @@ -3883,11 +3912,8 @@ the final result, after the throwing away.)) @opindex --sort @cindex general numeric sort @vindex LC_NUMERIC -Sort numerically, using the standard C function @code{strtold} to convert -a prefix of each line to a long double-precision floating point number. -This allows floating point numbers to be specified in scientific notation, -like @code{1.0e-34} and @code{10e100}. -The @env{LC_NUMERIC} locale determines the decimal-point character. +Sort numerically, converting a prefix of each line to a long +double-precision floating point number. @xref{Floating point}. Do not report overflow, underflow, or conversion errors. Use the following collating sequence: @@ -11209,6 +11235,7 @@ digits, but is printed according to the @env{LC_NUMERIC} category of the current locale. For example, in a locale whose radix character is a comma, the command @samp{printf %g 3.14} outputs @samp{3,14} whereas the command @samp{printf %g 3,14} is an error. +@xref{Floating point}. @kindex \@var{ooo} @kindex \x@var{hh} @@ -15664,8 +15691,7 @@ days 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 (using a period before any fractional -digits). +arbitrary floating point numbers. @xref{Floating point}. The only options are @option{--help} and @option{--version}. @xref{Common options}. @@ -15765,8 +15791,7 @@ When @var{increment} is not specified, it defaults to @samp{1}, even when @var{first} is larger than @var{last}. @var{first} also defaults to @samp{1}. So @code{seq 1} prints @samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output. -Floating-point numbers -may be specified (using a period before any fractional digits). +Floating-point numbers may be specified. @xref{Floating point}. The program accepts the following options. Also see @ref{Common options}. Options must precede operands. @@ -15843,7 +15868,8 @@ of @code{%x}. On most systems, seq can produce whole-number output for values up to at least @math{2^{53}}. Larger integers are approximated. The details -differ depending on your floating-point implementation, but a common +differ depending on your floating-point implementation. +@xref{Floating point}. A common case is that @command{seq} works with integers through @math{2^{64}}, and larger integers may not be numerically correct: -- 1.7.3
