Thu Jan 18 00:32:43 1996 Roland McGrath <roland@churchy.gnu.ai.mit.edu>
[kopensolaris-gnu/glibc.git] / manual / math.texi
index bb79e26..a97d76c 100644 (file)
@@ -1,4 +1,4 @@
-@node Mathematics
+@node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
 @chapter Mathematics
 
 This chapter contains information about functions for performing
@@ -8,27 +8,22 @@ these functions have prototypes declared in the header file
 @pindex math.h
 
 All of the functions that operate on floating-point numbers accept
-arguments and return results of type @code{double}.  In future revisions
-of the ANSI C standard, additional functions may be added that operate
-on @code{float} and @code{long double} values.  For example, @code{cosf}
-and @code{cosl} would be versions of the @code{cos} function that
-operate on @code{float} and @code{long double} arguments, respectively.
-In the meantime, you should avoid using these names yourself.
-@xref{Reserved Names}.
-
-@strong{Incomplete:}  This chapter doesn't have any examples.
+arguments and return results of type @code{double}.  In the future,
+there may be additional functions that operate on @code{float} and
+@code{long double} values.  For example, @code{cosf} and @code{cosl}
+would be versions of the @code{cos} function that operate on
+@code{float} and @code{long double} arguments, respectively.  In the
+meantime, you should avoid using these names yourself.  @xref{Reserved
+Names}.
 
 @menu
-* Domain and Range Errors::            How overflow conditions and the like
-                                        are reported.
-* Not a Number::                       Making NANs and testing for NANs.
-* Trigonometric Functions::            Sine, cosine, and tangent.
-* Inverse Trigonometric Functions::    Arc sine, arc cosine, and arc tangent.
-* Exponentiation and Logarithms::      Also includes square root.
-* Hyperbolic Functions::               Hyperbolic sine and friends.
-* Pseudo-Random Numbers::              Functions for generating pseudo-random
-                                        numbers.
-* Absolute Value::                     Absolute value functions.
+* Domain and Range Errors::     Detecting overflow conditions and the like.
+* Trig Functions::              Sine, cosine, and tangent.
+* Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
+* Exponents and Logarithms::    Also includes square root.
+* Hyperbolic Functions::        Hyperbolic sine and friends.
+* Pseudo-Random Numbers::       Functions for generating pseudo-random
+                                numbers.
 @end menu
 
 @node Domain and Range Errors
@@ -39,15 +34,17 @@ Many of the functions listed in this chapter are defined mathematically
 over a domain that is only a subset of real numbers.  For example, the
 @code{acos} function is defined over the domain between @code{-1} and
 @code{1}.  If you pass an argument to one of these functions that is
-outside the domain over which it is defined, the function returns
-an unspecified value and sets @code{errno} to @code{EDOM} to indicate
-a @dfn{domain error}.
+outside the domain over which it is defined, the function sets
+@code{errno} to @code{EDOM} to indicate a @dfn{domain error}.  On
+machines that support IEEE floating point, functions reporting error
+@code{EDOM} also return a NaN.
 
 Some of these functions are defined mathematically to result in a
 complex value over parts of their domains.  The most familiar example of
-this is taking the square root of a negative number.  Since the C
-language has no support for complex numbers, this is considered a
-domain error.
+this is taking the square root of a negative number.  The functions in
+this chapter take only real arguments and return only real values;
+therefore, if the value ought to be nonreal, this is treated as a domain
+error.
 
 @cindex range error
 A related problem is that the mathematical result of a function may not
@@ -55,23 +52,24 @@ be representable as a floating point number.  If magnitude of the
 correct result is too large to be represented, the function sets
 @code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
 returns a particular very large value (named by the macro
-@code{HUGE_VAL}) or its negation.
+@code{HUGE_VAL}) or its negation (@w{@code{- HUGE_VAL}}).
 
 If the magnitude of the result is too small, a value of zero is returned
 instead.  In this case, @code{errno} might or might not be
 set to @code{ERANGE}.
 
-None of the mathematical functions ever generates signals as a result of
-domain or range errors.  In particular, this means that you won't see
-@code{SIGFPE} signals generated within these functions.  (@xref{Signal
-Handling}, for more information about signals.)
-
 The only completely reliable way to check for domain and range errors is
 to set @code{errno} to @code{0} before you call the mathematical function 
 and test @code{errno} afterward.  As a consequence of this use of 
 @code{errno}, use of the mathematical functions is not reentrant if you
 check for errors.
 
+@c !!! this isn't always true at the moment....
+None of the mathematical functions ever generates signals as a result of
+domain or range errors.  In particular, this means that you won't see
+@code{SIGFPE} signals generated within these functions.  (@xref{Signal
+Handling}, for more information about signals.)
+
 @comment math.h
 @comment ANSI
 @deftypevr Macro double HUGE_VAL
@@ -85,39 +83,11 @@ mathematical functions in overflow situations.
 @end deftypevr
 
 For more information about floating-point representations and limits,
-@xref{Floating-Point Limits}.  In particular, the macro @code{DBL_MAX}
-might be more appropriate than @code{HUGE_VAL} for many uses.
-
-@node Not a Number
-@section ``Not a Number'' Values
-@cindex NAN
-@cindex not a number
-@cindex IEEE floating point
+see @ref{Floating Point Parameters}.  In particular, the macro
+@code{DBL_MAX} might be more appropriate than @code{HUGE_VAL} for many
+uses other than testing for an error in a mathematical function.
 
-The IEEE floating point format used by most modern computers supports
-values that are ``not a number''.  These values are called @dfn{NANs}.
-``Not a number'' values result from certain operations which have no
-meaningful numeric result, such as zero divided by zero or infinity
-divided by infinity.
-
-One noteworthy property of NANs is that they are not equal to
-themselves.  Thus, @code{x == x} can be 0 if the value of @code{x} is a
-NAN.  In fact, this is the way to test whether a value is a NAN or not:
-if it is not equal to itself, then it is a NAN.
-
-Almost any arithmetic operation in which one argument is a NAN returns
-a NAN.
-
-@comment math.h
-@comment GNU
-@deftypevr Macro double NAN
-An expression representing a value which is ``not a number''.  This
-macro is a GNU extension, available only on machines that support ``not
-a number'' values---that is to say, on all machines that support IEEE
-floating point.
-@end deftypevr
-
-@node Trigonometric Functions
+@node Trig Functions
 @section Trigonometric Functions
 @cindex trigonometric functions
 
@@ -129,9 +99,9 @@ that pi radians equals 180 degrees.
 The math library doesn't define a symbolic constant for pi, but you can
 define your own if you need one:
 
-@example
+@smallexample
 #define PI 3.14159265358979323846264338327
-@end example
+@end smallexample
 
 @noindent
 You can also compute the value of pi with the expression @code{acos
@@ -162,15 +132,15 @@ The following @code{errno} error conditions are defined for this function:
 
 @table @code
 @item ERANGE
-Mathematically, the tangent function has singularities at odd multiples of
-pi/2.  If the argument @var{x} is too close to one of these singularities,
-@code{tan} sets this error condition and returns either positive or
-negative @code{HUGE_VAL}.
+Mathematically, the tangent function has singularities at odd multiples
+of pi/2.  If the argument @var{x} is too close to one of these
+singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
+either positive or negative @code{HUGE_VAL}.
 @end table
 @end deftypefun
 
 
-@node Inverse Trigonometric Functions
+@node Inverse Trig Functions
 @section Inverse Trigonometric Functions
 @cindex inverse trigonmetric functions
 
@@ -186,13 +156,9 @@ sine is @var{x}.  The value is in units of radians.  Mathematically,
 there are infinitely many such values; the one actually returned is the
 one between @code{-pi/2} and @code{pi/2} (inclusive).
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-The argument @var{x} is out of range.  The arc sine function is defined
-mathematically only over the domain @code{-1} to @code{1}.
-@end table
+@code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
+out of range.  The arc sine function is defined mathematically only
+over the domain @code{-1} to @code{1}.
 @end deftypefun
 
 @comment math.h
@@ -203,13 +169,9 @@ whose cosine is @var{x}.  The value is in units of radians.
 Mathematically, there are infinitely many such values; the one actually
 returned is the one between @code{0} and @code{pi} (inclusive).
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-The argument @var{x} is out of range.  The arc cosine function is defined
-mathematically only over the domain @code{-1} to @code{1}.
-@end table
+@code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
+out of range.  The arc cosine function is defined mathematically only
+over the domain @code{-1} to @code{1}.
 @end deftypefun
 
 
@@ -236,20 +198,16 @@ If @var{x} and @var{y} are coordinates of a point in the plane,
 @code{atan2} returns the signed angle between the line from the origin
 to that point and the x-axis.  Thus, @code{atan2} is useful for
 converting Cartesian coordinates to polar coordinates.  (To compute the
-radial coordinate, use @code{hypot}; see @ref{Exponentiation and
+radial coordinate, use @code{hypot}; see @ref{Exponents and
 Logarithms}.)
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-Both the @var{x} and @var{y} arguments are zero; the value of the
-function is not defined in this case.
-@end table
+The function @code{atan2} sets @code{errno} to @code{EDOM} if both
+@var{x} and @var{y} are zero; the return value is not defined in this
+case.
 @end deftypefun
 
 
-@node Exponentiation and Logarithms
+@node Exponents and Logarithms
 @section Exponentiation and Logarithms
 @cindex exponentiation functions
 @cindex power functions
@@ -261,12 +219,8 @@ function is not defined in this case.
 The @code{exp} function returns the value of e (the base of natural
 logarithms) raised to power @var{x}.
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item ERANGE
-The magnitude of the result is too large to be representable.
-@end table
+The function fails, and sets @code{errno} to @code{ERANGE}, if the
+magnitude of the result is too large to be representable.
 @end deftypefun
 
 @comment math.h
@@ -280,12 +234,11 @@ The following @code{errno} error conditions are defined for this function:
 
 @table @code
 @item EDOM
-The log function is defined mathematically to return a non-complex
-result only on positive arguments.  This error is used to report a
-negative argument @var{x}.
+The argument @var{x} is negative.  The log function is defined
+mathematically to return a real result only on positive arguments.
 
 @item ERANGE
-The result of the function on an argument of zero is not defined.
+The argument is zero.  The log of zero is not defined.
 @end table
 @end deftypefun
 
@@ -303,6 +256,7 @@ different base, it is similar to the @code{log} function.  In fact,
 This is a general exponentiation function, returning @var{base} raised
 to @var{power}.
 
+@need 250
 The following @code{errno} error conditions are defined for this function:
 
 @table @code
@@ -321,41 +275,31 @@ An underflow or overflow condition was detected in the result.
 @deftypefun double sqrt (double @var{x})
 This function returns the nonnegative square root of @var{x}.
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-The argument @var{x} is negative.  Mathematically, the square root would
-be a complex number.
-@end table
+The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
+@var{x} is negative.  Mathematically, the square root would be a complex
+number.
 @end deftypefun
 
 @cindex cube root function
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double cbrt (double @var{x})
-This function returns the cube root of @var{x}.
+This function returns the cube root of @var{x}.  This function cannot
+fail; every representable real value has a representable real cube root.
 @end deftypefun
 
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double hypot (double @var{x}, double @var{y})
 The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
 triangle with sides of length @var{x} and @var{y}, or the distance
-of the point (@var{x}, @var{y}) from the origin.)
+of the point (@var{x}, @var{y}) from the origin.)  See also the function
+@code{cabs} in @ref{Absolute Value}.
 @end deftypefun
 
 @comment math.h
-@comment GNU
-@deftypefun double cabs (struct @{ double x, y; @} @var{z})
-The @code{cabs} function is similar to @code{hypot}, but the argument
-is specified as a @code{struct} representing a complex number.
-@end deftypefun
-
-
-@comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double expm1 (double @var{x})
 This function returns a value equivalent to @code{exp (@var{x}) - 1}.
 It is computed in a way that is accurate even if the value of @var{x} is
@@ -364,9 +308,9 @@ to subtraction of two numbers that are nearly equal.
 @end deftypefun
 
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double log1p (double @var{x})
-This function returns a value equivalent to @code{log (1 + @var{x})}.
+This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
 It is computed in a way that is accurate even if the value of @var{x} is
 near zero.
 @end deftypefun
@@ -376,56 +320,44 @@ near zero.
 @cindex hyperbolic functions
 
 The functions in this section are related to the exponential functions;
-see @ref{Exponentiation and Logarithms}.
+see @ref{Exponents and Logarithms}.
 
 @comment math.h
 @comment ANSI
 @deftypefun double sinh (double @var{x})
 The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
-mathematically as @code{(exp (@var{x}) - exp (-@var{x}) / 2}.
-The following @code{errno} error conditions are defined for this
-function:
-
-@table @code
-@item ERANGE
-The value of the argument @var{x} is too large; an overflow condition
-was detected.
-@end table
+mathematically as @w{@code{exp (@var{x}) - exp (-@var{x}) / 2}}.  The
+function fails, and sets @code{errno} to @code{ERANGE}, if the value of
+@var{x} is too large; that is, if overflow occurs.
 @end deftypefun
 
 @comment math.h
 @comment ANSI
 @deftypefun double cosh (double @var{x})
 The @code{cosh} function returns the hyperbolic cosine of @var{x},
-defined mathematically as @code{(exp (@var{x}) + exp (-@var{x}) /
-2}.  The following @code{errno} error conditions are defined for this
-function:
-
-@table @code
-@item ERANGE
-The value of the argument @var{x} is too large; an overflow condition
-was detected.
-@end table
+defined mathematically as @w{@code{exp (@var{x}) + exp (-@var{x}) / 2}}.
+The function fails, and sets @code{errno} to @code{ERANGE}, if the value
+of @var{x} is too large; that is, if overflow occurs.
 @end deftypefun
 
 @comment math.h
 @comment ANSI
 @deftypefun double tanh (double @var{x})
-This function returns the hyperbolic tangent of @var{x}, defined
-mathematically as @code{sinh (@var{x}) / cosh (@var{x})}.
+This function returns the hyperbolic tangent of @var{x}, whose 
+mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
 @end deftypefun
 
 @cindex inverse hyperbolic functions
 
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double asinh (double @var{x})
 This function returns the inverse hyperbolic sine of @var{x}---the
 value whose hyperbolic sine is @var{x}.
 @end deftypefun
 
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double acosh (double @var{x})
 This function returns the inverse hyperbolic cosine of @var{x}---the
 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
@@ -433,7 +365,7 @@ value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
 @end deftypefun
 
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double atanh (double @var{x})
 This function returns the inverse hyperbolic tangent of @var{x}---the
 value whose hyperbolic tangent is @var{x}.  If the absolute value of
@@ -443,48 +375,46 @@ value whose hyperbolic tangent is @var{x}.  If the absolute value of
 
 @node Pseudo-Random Numbers
 @section Pseudo-Random Numbers
-
-This section describes the GNU facilities for generating a series of
-pseudo-random numbers.  The numbers generated are not necessarily truly
-random; typically, the sequences repeat periodically, with the period
-being a function of the number of bits in the @dfn{seed} or initial
-state.
 @cindex random numbers
 @cindex pseudo-random numbers
 @cindex seed (for random numbers)
 
-There are actually two sets of random number functions provided.
-
-@itemize @bullet
-@item 
-The @code{rand} and @code{srand} functions, described in @ref{ANSI C
-Random Number Functions}, are part of the ANSI C standard.  You can use
-these functions portably in many C implementations.
-
-@item 
-The @code{random} and @code{srandom} functions, described in @ref{BSD
-Random Number Functions}, are derived from BSD Unix.  This uses a better
-random number generator (producing numbers that are more random), but
-is less portable.
-@end itemize
-
-For both sets of functions, you can get repeatable sequences of numbers
-within a single implementation on a single machine type by specifying
-the same initial seed value for the random number generator.  Other C
-libraries may produce different sequences of values for the same seed.
-
+This section describes the GNU facilities for generating a series of
+pseudo-random numbers.  The numbers generated are not truly random;
+typically, they form a sequence that repeats periodically, with a
+period so large that you can ignore it for ordinary purposes.  The
+random number generator works by remembering at all times a @dfn{seed}
+value which it uses to compute the next random number and also to
+compute a new seed.
+
+Although the generated numbers look unpredictable within one run of a
+program, the sequence of numbers is @emph{exactly the same} from one run
+to the next.  This is because the initial seed is always the same.  This
+is convenient when you are debugging a program, but it is unhelpful if
+you want the program to behave unpredictably.  If you want truly random
+numbers, not just pseudo-random, specify a seed based on the current
+time.
+
+You can get repeatable sequences of numbers on a particular machine type
+by specifying the same initial seed value for the random number
+generator.  There is no standard meaning for a particular seed value;
+the same seed, used in different C libraries or on different CPU types,
+will give you different random numbers.
+
+The GNU library supports the standard ANSI C random number functions
+plus another set derived from BSD.  We recommend you use the standard
+ones, @code{rand} and @code{srand}.
 
 @menu
-* ANSI C Random Number Functions::     @code{rand} and friends.
-* BSD Random Number Functions::                @code{random} and friends.
+* ANSI Random::      @code{rand} and friends.
+* BSD Random::       @code{random} and friends.
 @end menu
 
-@node ANSI C Random Number Functions
+@node ANSI Random
 @subsection ANSI C Random Number Functions
 
 This section describes the random number functions that are part of
-the ANSI C standard.  These functions represent the state of the
-random number generator as an @code{int}.
+the ANSI C standard.
 
 To use these facilities, you should include the header file
 @file{stdlib.h} in your program.
@@ -495,13 +425,14 @@ To use these facilities, you should include the header file
 @deftypevr Macro int RAND_MAX
 The value of this macro is an integer constant expression that
 represents the maximum possible value returned by the @code{rand}
-function.  In the GNU library, it is @code{037777777}.  In other
-libraries, it may be as low as @code{32767}.
+function.  In the GNU library, it is @code{037777777}, which is the
+largest signed integer representable in 32 bits.  In other libraries, it
+may be as low as @code{32767}.
 @end deftypevr
 
 @comment stdlib.h
 @comment ANSI
-@deftypefun int rand (void)
+@deftypefun int rand ()
 The @code{rand} function returns the next pseudo-random number in the
 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
 @end deftypefun
@@ -518,20 +449,19 @@ To produce truly random numbers (not just pseudo-random), do @code{srand
 (time (0))}.
 @end deftypefun
 
-@node BSD Random Number Functions
+@node BSD Random
 @subsection BSD Random Number Functions
 
-This section describes a set of random number generation functions
-that are derived from BSD Unix.  The @code{random} function can generate
-better random numbers than @code{rand}, because it maintains more bits
-of internal state.
+This section describes a set of random number generation functions that
+are derived from BSD.  There is no advantage to using these functions
+with the GNU C library; we support them for BSD compatibility only.
 
 The prototypes for these functions are in @file{stdlib.h}.
 @pindex stdlib.h
 
 @comment stdlib.h
 @comment BSD
-@deftypefun {long int} random (void)
+@deftypefun {long int} random ()
 This function returns the next pseudo-random number in the sequence.
 The range of values returned is from @code{0} to @code{RAND_MAX}.
 @end deftypefun
@@ -548,12 +478,6 @@ To produce truly random numbers (not just pseudo-random), do
 @code{srandom (time (0))}.
 @end deftypefun
 
-Because this random number generator uses more state information than
-will fit in an @code{int}, @code{srandom} does not return a value that
-is useful for saving and restoring the random number state.  Instead,
-you should use the @code{initstate} and @code{setstate} functions to do
-this.
-
 @comment stdlib.h
 @comment BSD
 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
@@ -579,43 +503,3 @@ The return value is the previous value of the state information array.
 You can use thise value later as an argument to @code{setstate} to
 restore that state.
 @end deftypefun
-
-@node Absolute Value
-@section Absolute Value
-@cindex absolute value functions
-
-These functions are provided for obtaining the @dfn{absolute value} (or
-@dfn{magnitude}) of a number.  The absolute value of @var{x} is @var{x}
-is @var{x} is positive, @minus{}@var{x} if @var{x} is negative.
-
-Prototypes for @code{abs} and @code{abs} are declared in
-@file{stdlib.h}; @code{fabs} is declared in @file{math.h}.
-@pindex math.h
-@pindex stdlib.h
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun int abs (int @var{number})
-This function returns the absolute value of @var{number}.
-
-Most computers use a two's complement integer representation, in which
-the absolute value of @code{INT_MIN} (the smallest possible @code{int})
-cannot be represented; thus, @code{abs (INT_MIN)} is not defined.
-@end deftypefun
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun {long int} labs (long int @var{number})
-This is similar to @code{abs}, except that both the argument and result
-are of type @code{long int} rather than @code{int}.
-@end deftypefun
-
-@comment math.h
-@comment ANSI
-@deftypefun double fabs (double @var{number})
-This function returns the absolute value of the floating-point number
-@var{number}.
-@end deftypefun
-
-There is also the function @code{cabs} for computing the absolute value
-of a complex number; see @ref{Exponentiation and Logarithms}.