Thu Jan 18 00:32:43 1996 Roland McGrath <roland@churchy.gnu.ai.mit.edu>
[kopensolaris-gnu/glibc.git] / manual / math.texi
index f83569c..a97d76c 100644 (file)
@@ -34,9 +34,10 @@ 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
@@ -51,7 +52,7 @@ 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
@@ -63,6 +64,7 @@ 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
@@ -97,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
@@ -254,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
@@ -279,10 +282,10 @@ number.
 
 @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 cannot
-fail; every representable real value has a represetable real cube root.
+fail; every representable real value has a representable real cube root.
 @end deftypefun
 
 @comment math.h
@@ -307,7 +310,7 @@ to subtraction of two numbers that are nearly equal.
 @comment math.h
 @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
@@ -323,7 +326,7 @@ see @ref{Exponents and Logarithms}.
 @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
+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
@@ -332,7 +335,7 @@ function fails, and sets @code{errno} to @code{ERANGE}, if the value of
 @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}.
+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
@@ -340,8 +343,8 @@ of @var{x} is too large; that is, if overflow occurs.
 @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
@@ -372,36 +375,35 @@ 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
-Random}, 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}, are derived from BSD.  They use a better random number
-generator (producing numbers that are more random), but are 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 Random::      @code{rand} and friends.
@@ -412,8 +414,7 @@ libraries may produce different sequences of values for the same seed.
 @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.
@@ -424,8 +425,9 @@ 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
@@ -451,9 +453,8 @@ To produce truly random numbers (not just pseudo-random), do @code{srand
 @subsection BSD Random Number Functions
 
 This section describes a set of random number generation functions that
-are derived from BSD.  The @code{random} function can generate better
-random numbers than @code{rand}, because it maintains more bits of
-internal state.
+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
@@ -477,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})