about summary refs log tree commit diff
path: root/manual/math.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/math.texi')
-rw-r--r--manual/math.texi1395
1 files changed, 454 insertions, 941 deletions
diff --git a/manual/math.texi b/manual/math.texi
index 1991bfbdb8..10b326287e 100644
--- a/manual/math.texi
+++ b/manual/math.texi
@@ -1,739 +1,129 @@
 @c We need some definitions here.
+@ifclear mult
 @ifhtml
-@set mult ·
+@set mult ·
+@set infty ∞
+@set pie π
 @end ifhtml
 @iftex
 @set mult @cdot
+@set infty @infty
 @end iftex
 @ifclear mult
-@set mult x
+@set mult *
+@set infty oo
+@set pie pi
 @end ifclear
 @macro mul
 @value{mult}
 @end macro
-@iftex
-@set infty @infty
-@end iftex
-@ifclear infty
-@set infty oo
-@end ifclear
 @macro infinity
 @value{infty}
 @end macro
+@ifnottex
+@macro pi
+@value{pie}
+@end macro
+@end ifnottex
+@end ifclear
 
 @node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
+@c %MENU% Math functions, useful constants, random numbers
 @chapter Mathematics
 
 This chapter contains information about functions for performing
 mathematical computations, such as trigonometric functions.  Most of
 these functions have prototypes declared in the header file
-@file{math.h}.
+@file{math.h}.  The complex-valued functions are defined in
+@file{complex.h}.
 @pindex math.h
-
-For all functions which take a single floating-point argument and for
-several other functions as well there are three different functions
-available for the type @code{double}, @code{float}, and @code{long
-double}.  The @code{double} versions of the functions are mostly defined
-even in the @w{ISO C 89} standard.  The @code{float} and @code{long
-double} variants are introduced in the numeric extensions for the C
-language which are part of the @w{ISO C 9X} standard.
-
-Which of the three versions of the function should be used depends on
-the situation.  For most functions and implementation it is true that
-speed and precision do not go together.  I.e., the @code{float} versions
-are normally faster than the @code{double} and @code{long double}
-versions.  On the other hand the @code{long double} version has the
-highest precision.  One should always think about the actual needs and
-in case of double using @code{double} is a good compromise.
-
+@pindex complex.h
+
+All mathematical functions which take a floating-point argument
+have three variants, one each for @code{double}, @code{float}, and
+@code{long double} arguments.  The @code{double} versions are mostly
+defined in @w{ISO C 89}.  The @code{float} and @code{long double}
+versions are from the numeric extensions to C included in @w{ISO C 9X}.
+
+Which of the three versions of a function should be used depends on the
+situation.  For most calculations, the @code{float} functions are the
+fastest.  On the other hand, the @code{long double} functions have the
+highest precision.  @code{double} is somewhere in between.  It is
+usually wise to pick the narrowest type that can accomodate your data.
+Not all machines have a distinct @code{long double} type; it may be the
+same as @code{double}.
 
 @menu
-* Domain and Range Errors::      Detecting overflow conditions and the like.
-* Exceptions in Math Functions:: Signalling exception in math functions.
-* Mathematical Constants::       Precise numeric values for often used
-                                  constant.
-* FP Comparison Functions::      Special functions to compare floating-point
-                                  numbers.
-* FP Function Optimizations::    Fast code or small code.
-* 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.
+* Mathematical Constants::      Precise numeric values for often-used
+                                 constants.
+* Trig Functions::              Sine, cosine, tangent, and friends.
+* Inverse Trig Functions::      Arcsine, arccosine, etc.
+* Exponents and Logarithms::    Also pow and sqrt.
+* Hyperbolic Functions::        sinh, cosh, tanh, etc.
+* Special Functions::           Bessel, gamma, erf.
+* Pseudo-Random Numbers::       Functions for generating pseudo-random
+				 numbers.
+* FP Function Optimizations::   Fast code or small code.
 @end menu
 
-@node Domain and Range Errors
-@section Domain and Range Errors
-
-@cindex domain error
-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{@minus{}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 sets
-@code{errno} to @code{EDOM} to indicate a @dfn{domain error}.  On
-machines that support @w{IEEE 754} 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.  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
-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{@minus{}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}.
-
-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 is no longer true.  --drepper
-@c None of the mathematical functions ever generates signals as a result of
-@c domain or range errors.  In particular, this means that you won't see
-@c @code{SIGFPE} signals generated within these functions.  (@xref{Signal
-@c Handling}, for more information about signals.)
-
-@comment math.h
-@comment ISO
-@deftypevr Macro double HUGE_VAL
-An expression representing a particular very large number.  On machines
-that use @w{IEEE 754}/@w{IEEE 854} floating point format, the value is
-``infinity''.  On other machines, it's typically the largest positive
-number that can be represented.
-
-The value of this macro is used as the return value from various
-mathematical @code{double} returning functions in overflow situations.
-@end deftypevr
-
-@comment math.h
-@comment ISO
-@deftypevr Macro float HUGE_VALF
-This macro is similar to the @code{HUGE_VAL} macro except that it is
-used by functions returning @code{float} values.
-
-This macro is introduced in @w{ISO C 9X}.
-@end deftypevr
-
-@comment math.h
-@comment ISO
-@deftypevr Macro {long double} HUGE_VALL
-This macro is similar to the @code{HUGE_VAL} macro except that it is
-used by functions returning @code{long double} values.  The value is
-only different from @code{HUGE_VAL} if the architecture really supports
-@code{long double} values.
-
-This macro is introduced in @w{ISO C 9X}.
-@end deftypevr
-
-
-A special case is the @code{ilogb} function @pxref{Exponents and
-Logarithms}.  Since the return value is an integer value, one cannot
-compare with @code{HUGE_VAL} etc.  Therefore two further values are
-defined.
-
-@comment math.h
-@comment ISO
-@deftypevr Macro int FP_ILOGB0
-This value is returned by @code{ilogb} if the argument is @code{0}.  The
-numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
-
-This macro is introduced in @w{ISO C 9X}.
-@end deftypevr
-
-@comment math.h
-@comment ISO
-@deftypevr Macro int FP_ILOGBNAN
-This value is returned by @code{ilogb} if the argument is @code{NaN}.  The
-numeric value is either @code{INT_MIN} or @code{INT_MAX}.
-
-This macro is introduced in @w{ISO C 9X}.
-@end deftypevr
-
-
-For more information about floating-point representations and limits,
-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.
-
-
-@node Exceptions in Math Functions
-@section Exceptions in Math Functions
-@cindex exception
-@cindex signal
-
-Due to the restrictions in the size of the floating-point number
-representation or the limitation of the input range of certain functions
-some of the mathematical operations and functions have to signal
-exceptional situations.  The @w{IEEE 754} standard specifies which
-exceptions have to be supported and how they can be handled.
-
-@w{IEEE 754} specifies two actions for floating-point exception: taking
-a trap or continuing without doing so.  If the trap is taken a
-(possibly) user defined trap handler is called and this function can
-correct the argument or react somehow else on the call.  If the trap
-handler returns, its return value is taken as the result of the
-operation.
-
-If no trap handler is called each of the known exceptions has a default
-action.  This consists of setting a corresponding bit in the
-floating-point status word to indicate which kind of exception was
-raised and to return a default value, which depends on the exception
-(see the table below).
-
-@noindent
-The exceptions defined in @w{IEEE 754} are:
-
-@table @samp
-@item Invalid Operation
-This exception is raised if the given operands are invalid for the
-operation to be performed.  Examples are
-(see @w{IEEE 754}, @w{section 7}):
-@enumerate
-@item
-Any operation on a signalling NaN.
-@item
-Addition or subtraction; magnitude subtraction of infinities such as
-@math{(+@infinity{}) + (-@infinity{})}.
-@item
-Multiplication:
-@math{0 @mul{} @infinity{}}.
-
-@item
-Division: @math{0/0} or @math{@infinity{}/@infinity{}}.
-
-@item
-Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is
-infinite.
-@item
-Square root if the operand is less then zero.
-@item
-Conversion of an internal floating-point number to an integer or to a
-decimal string when overflow, infinity, or NaN precludes a faithful
-representation in that format and this cannot otherwise be signaled.
-@item
-Conversion of an unrecognizable input string.
-@item
-Comparison via predicates involving @math{<} or @math{>}, without
-@code{?}, when the operands are @dfn{unordered}.  (@math{?>} means the
-unordered greater relation, @xref{FP Comparison Functions}).
-@end enumerate
-
-If the exception does not cause a trap handler to be called the result
-of the operation is taken as a quiet NaN.
-
-@item Division by Zero
-This exception is raised if the divisor is zero and the dividend is a
-finite nonzero number.  If no trap occurs the result is either
-@math{+@infinity{}} or @math{-@infinity{}}, depending on the
-signs of the operands.
-
-@item Overflow
-This exception is signalled whenever the result cannot be represented
-as a finite value in the precision format of the destination.  If no trap
-occurs the result depends on the sign of the intermediate result and the
-current rounding mode (@w{IEEE 754}, @w{section 7.3}):
-@enumerate
-@item
-Round to nearest carries all overflows to @math{@infinity{}}
-with the sign of the intermediate result.
-@item
-Round toward @math{0} carries all overflows to the precision's largest
-finite number with the sign of the intermediate result.
-@item
-Round toward @math{-@infinity{}} carries positive overflows to the
-precision's largest finite number and carries negative overflows to
-@math{-@infinity{}}.
-
-@item
-Round toward @math{@infinity{}} carries negative overflows to the
-precision's most negative finite number and carries positive overflows
-to @math{@infinity{}}.
-@end enumerate
-
-@item Underflow
-The underflow exception is created when an intermediate result is too
-small for the operation or if the operations result rounded to the
-destination precision causes a loss of accuracy by approximating the
-result by denormalized numbers.
-
-When no trap is installed for the underflow exception, underflow shall
-be signaled (via the underflow flag) only when both tininess and loss of
-accuracy have been detected.  If no trap handler is installed the
-operation continues with an inprecise small value or zero if the
-destination precision cannot hold the small exact result.
-
-@item Inexact
-This exception is signalled if the rounded result is not exact (such as
-computing the square root of two) or the result overflows without an
-overflow trap.
-@end table
-
-To control whether an exception causes a trap to occur all @w{IEEE 754}
-conformant floating-point implementations (either hardware or software)
-have a control word.  By setting specific bits for each exception in
-this control word the programmer can decide whether a trap is wanted or
-not.
-
-@w{ISO C 9X} introduces a set of function which can be used to control
-exceptions.  There are functions to manipulate the control word, to
-query the status word or to save and restore the whole state of the
-floating-point unit.  There are also functions to control the rounding
-mode used.
-
-@menu
-* Status bit operations::       Manipulate the FP status word.
-* FPU environment::             Controlling the status of the FPU.
-* Rounding Modes::              Controlling the rounding mode.
-@end menu
-
-@node Status bit operations
-@subsection Controlling the FPU status word
-
-To control the five types of exceptions defined in @w{IEEE 754} some
-functions are defined which abstract the interface to the FPU.  The
-actual implementation can be very different, depending on the underlying
-hardware or software.
-
-To address the single exception the @file{fenv.h} headers defines a
-number of macros:
-
-@vtable @code
-@comment fenv.h
-@comment ISO
-@item FE_INEXACT
-Represents the inexact exception iff the FPU supports this exception.
-@comment fenv.h
-@comment ISO
-@item FE_DIVBYZERO
-Represents the divide by zero exception iff the FPU supports this exception.
-@comment fenv.h
-@comment ISO
-@item FE_UNDERFLOW
-Represents the underflow exception iff the FPU supports this exception.
-@comment fenv.h
-@comment ISO
-@item FE_OVERFLOW
-Represents the overflow exception iff the FPU supports this exception.
-@comment fenv.h
-@comment ISO
-@item FE_INVALID
-Represents the invalid exception iff the FPU supports this exception.
-@end vtable
-
-The macro @code{FE_ALL_EXCEPT} is the bitwise OR of all exception macros
-which are supported by the FP implementation.
-
-Each of the supported exception flags can either be set or unset.  The
-@w{ISO C 9X} standard defines functions to set, unset and test the
-status of the flags.
-
-@comment fenv.h
-@comment ISO
-@deftypefun void feclearexcept (int @var{excepts})
-This function clears all of the supported exception flags denoted by
-@var{excepts} in the status word.
-@end deftypefun
-
-To safe the current status of the flags in the status word @file{fenv.h}
-defines the type @code{fexcept_t} which can hold all the information.
-The following function can be used to retrieve the current setting.
-
-@comment fenv.h
-@comment ISO
-@deftypefun void fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts})
-Store in the variable pointed to by @var{flagp} an
-implementation-defined value representing the current setting of the
-exception flags indicated by the parameter @var{excepts}.
-@end deftypefun
-
-@noindent
-To restore the previously saved values one can use this function:
-
-@comment fenv.h
-@comment ISO
-@deftypefun void fesetexceptflag (const fexcept_t *@var{flagp}, int @var{excepts})
-Restore from the variable pointed to by @var{flagp} the setting of the
-flags for the exceptions denoted by the value of the parameter
-@var{excepts}.
-@end deftypefun
-
-The last function allows to query the current status of the flags.  The
-flags can be set either explicitely (using @code{fesetexceptflag} or
-@code{feclearexcept}) or by a floating-point operation which happened
-before.  Since the flags are accumulative, the flags must be explicitely
-reset using @code{feclearexcept} if one wants to test for a certain
-exceptions raised by a specific piece of code.
-
-@comment fenv.h
-@comment ISO
-@deftypefun int fetestexcept (int @var{excepts})
-Test whether a subset of the flags indicated by the parameter
-@var{except} is currently set.  If yes, a nonzero value is returned
-which specifies which exceptions are set.  Otherwise the result is zero.
-@end deftypefun
-
-@noindent
-Code which uses the @code{fetestexcept} function could look like this:
-
-@smallexample
-@{
-  double f;
-  int raised;
-  feclearexcept (FE_ALL_EXCEPT);
-  f = compute ();
-  raised = fetestexcept (FE_OVERFLOW | FE_INVALID);
-  if (raised & FE_OVERFLOW) @{ /* ... */ @}
-  if (raised & FE_INVALID) @{ /* ... */ @}
-  /* ... */
-@}
-@end smallexample
-
-Please note that the return value of @code{fetestexcept} is @code{int}
-but this does not mean that the @code{fexcept_t} type is generally
-representable as an integer.  These are completely independent types.
-
-
-@node FPU environment
-@subsection Controlling the Floating-Point environment
-
-It is sometimes necessary so save the complete status of the
-floating-point unit for a certain time to perform some completely
-different actions.  Beside the status of the exception flags, the
-control word for the exceptions and the rounding mode can be saved.
-
-The file @file{fenv.h} defines the type @code{fenv_t}.  The layout of a
-variable of this type is implementation defined but the variable is able
-to contain the complete status information.  To fill a variable of this
-type one can use this function:
-
-@comment fenv.h
-@comment ISO
-@deftypefun void fegetenv (fenv_t *@var{envp})
-Store the current floating-point environment in the object pointed to by
-@var{envp}.
-@end deftypefun
-
-@noindent
-Another possibility which is useful in several situations is
-
-@comment fenv.h
-@comment ISO
-@deftypefun int feholdexcept (fenv_t *@var{envp})
-Store the current floating-point environment in the object pointed to by
-@var{envp}.  Afterwards, all exception flags are cleared and if
-available a mode is installed which continues on all exceptions and does
-not cause a trap to occur.  In this case a nonzero value is returned.
-
-If the floating-point implementation does not support such a non-stop
-mode, the return value is zero.
-@end deftypefun
-
-The functions which allow a state of the floating-point unit to be
-restored can take two kinds of arguments:
-
-@itemize @bullet
-@item
-Pointers to @code{fenv_t} objects which were initialized previously by a
-call to @code{fegetenv} or @code{feholdexcept}.
-@item
-@vindex FE_DFL_ENV
-The special macro @code{FE_DFL_ENV} which represents the floating-point
-environment as it was available at program start.
-@item
-Implementation defined macros with names starting with @code{FE_}.
-
-@vindex FE_NOMASK_ENV
-If possible, the GNU C Library defines a macro @code{FE_NOMASK_ENV}
-which represents an environment where no exceptions are masked, so every
-exception raised causes a trap to occur.  You can test for this macro
-using @code{#ifdef}.
-
-Some platforms might define other predefined environments.
-@end itemize
-
-@noindent
-To set any of the environments there are two functions defined.
-
-@deftypefun void fesetenv (const fenv_t *@var{envp})
-Establish the floating-point environment described in the object pointed
-to by @var{envp}.  Even if one or more exceptions flags in the restored
-environment are set no exception is raised.
-@end deftypefun
-
-In some situations the previous status of the exception flags must not
-simply be discarded and so this function is useful:
-
-@deftypefun void feupdateenv (const fenv_t *@var{envp})
-The current status of the floating-point unit is preserved in some
-automatic storage before the environment described by the object pointed
-to by @var{envp} is installed.  Once this is finished all exceptions set
-in the original environment which is saved in the automatic storage, is
-raised.
-@end deftypefun
-
-This function can be used to execute a part of the program with an
-environment which masks all exceptions and before switching back remove
-unwanted exception and raise the remaining exceptions.
-
-
-@node Rounding Modes
-@subsection Rounding modes of the Floating-Point Unit
-
-@w{IEEE 754} defines four different rounding modes.  If the rounding
-mode is supported by the floating-point implementation the corresponding
-of the following macros is defined:
-
-@table @code
-@comment fenv.h
-@comment ISO
-@vindex FE_TONEAREST
-@item FE_TONEAREST
-Round to nearest.  This is the default mode and should always be used
-except when a different mode is explicitely required.  Only rounding to
-nearest guarantees numeric stability of the computations.
-
-@comment fenv.h
-@comment ISO
-@vindex FE_UPWARD
-@item FE_UPWARD
-Round toward @math{+@infinity{}}.
-
-@comment fenv.h
-@comment ISO
-@vindex FE_DOWNWARD
-@item FE_DOWNWARD
-Round toward @math{-@infinity{}}.
-
-@comment fenv.h
-@comment ISO
-@vindex FE_TOWARDZERO
-@item FE_TOWARDZERO
-Round toward zero.
-@end table
-
-At any time one of the above four rounding modes is selected.  To get
-information about the currently selected mode one can use this function:
-
-@comment fenv.h
-@comment ISO
-@deftypefun int fegetround (void)
-Return the currently selected rounding mode, represented by one of the
-values of the defined rounding mode macros.
-@end deftypefun
-
-@noindent
-To set a specific rounding mode the next function can be used.
-
-@comment fenv.h
-@comment ISO
-@deftypefun int fesetround (int @var{round})
-Change the currently selected rounding mode to the mode described by the
-parameter @var{round}.  If @var{round} does not correspond to one of the
-supported rounding modes nothing is changed.
-
-The function returns a nonzero value iff the requested rounding mode can
-be established.  Otherwise zero is returned.
-@end deftypefun
-
-Changing the rounding mode might be necessary for various reasons.  But
-changing the mode only to round a given number normally is no good idea.
-The standard defines a set of functions which can be used to round an
-argument according to some rules and for all of the rounding modes there
-is a corresponding function.
-
-If a large set of number has to be rounded it might be good to change
-the rounding mode and to not use the function the library provides.  So
-the perhaps necessary switching of the rounding mode in the library
-function can be avoided.  But since not all rounding modes are
-guaranteed to exist on any platform this possible implementation cannot
-be portably used.  A default method has to be implemented as well.
-
-
 @node Mathematical Constants
 @section Predefined Mathematical Constants
 @cindex constants
 @cindex mathematical constants
 
-The header @file{math.h} defines a series of mathematical constants if
-@code{_BSD_SOURCE} or a more general feature select macro is defined
-before including this file.  All values are defined as preprocessor
-macros starting with @code{M_}.  The collection includes:
+The header @file{math.h} defines several useful mathematical constants.
+All values are defined as preprocessor macros starting with @code{M_}.
+The values provided are:
 
 @vtable @code
 @item M_E
-The value is that of the base of the natural logarithm.
+The base of natural logarithms.
 @item M_LOG2E
-The value is computed as the logarithm to base @code{2} of @code{M_E}.
+The logarithm to base @code{2} of @code{M_E}.
 @item M_LOG10E
-The value is computed as the logarithm to base @code{10} of @code{M_E}.
+The logarithm to base @code{10} of @code{M_E}.
 @item M_LN2
-The value is computed as the natural logarithm of @code{2}.
+The natural logarithm of @code{2}.
 @item M_LN10
-The value is computed as the natural logarithm of @code{10}.
+The natural logarithm of @code{10}.
 @item M_PI
-The value is those of the number pi.
+Pi, the ratio of a circle's circumrefence to its diameter.
 @item M_PI_2
-The value is those of the number pi divided by two.
+Pi divided by two.
 @item M_PI_4
-The value is those of the number pi divided by four.
+Pi divided by four.
 @item M_1_PI
-The value is the reziprocal of the value of the number pi.
+The reciprocal of pi (1/pi)
 @item M_2_PI
-The value is two times the reziprocal of the value of the number pi.
+Two times the reciprocal of pi.
 @item M_2_SQRTPI
-The value is two times the reziprocal of the square root of the number pi.
+Two times the reciprocal of the square root of pi.
 @item M_SQRT2
-The value is the square root of the value of the number pi.
+The square root of two.
 @item M_SQRT1_2
-The value is the reziprocal of the square root of the value of the number pi.
+The reciprocal of the square root of two (also the square root of 1/2).
 @end vtable
 
-All values are defined as @code{long double} values unless the compiler
-does not support this type or @code{__STDC__} is not defined (both is
-unlikely).  Historically the numbers were @code{double} values and some
-old code still relies on this so you might want to add explicit casts if
-the extra precision of the @code{long double} value is not needed.  One
-critical case are functions with a variable number of arguments, such as
-@code{printf}.
+These constants come from the Unix98 standard and were also available in
+4.4BSD; therefore, they are only defined if @code{_BSD_SOURCE} or
+@code{_XOPEN_SOURCE=500}, or a more general feature select macro, is
+defined.  The default set of features includes these constants.
+@xref{Feature Test Macros}.
+
+All values are of type @code{double}.  As an extension, the GNU C
+library also defines these constants with type @code{long double}.  The
+@code{long double} macros have a lowercase @samp{l} appended to their
+names: @code{M_El}, @code{M_PIl}, and so forth.  These are only
+available if @code{_GNU_SOURCE} is defined.
 
 @vindex PI
 @emph{Note:} Some programs use a constant named @code{PI} which has the
-same value as @code{M_PI}.  This probably derives from Stroustroup's
-book about his C++ programming language where this value is used in
-examples (and perhaps some AT&T headers contain this value).  But due to
-possible name space problems (@code{PI} is a quite frequently used name)
-this value is not added to @file{math.h}.  Every program should use
-@code{M_PI} instead or add on the compiler command line
-@code{-DPI=M_PI}.
-
-
-@node FP Comparison Functions
-@section Floating-Point Comparison Functions
-@cindex unordered comparison
-
-The @w{IEEE 754} standards defines a set of functions which allows to
-compare even those numbers which normally would cause an exception to be
-raised since they are unordered.  E.g., the expression
-
-@smallexample
-int v = a < 1.0;
-@end smallexample
-
-@noindent
-would raise an exception if @var{a} would be a NaN.  Functions to
-compare unordered numbers are part of the FORTRAN language for a long
-time and the extensions in @w{ISO C 9X} finally introduce them as well
-for the C programming language.
-
-All of the operations are implemented as macros which allow their
-arguments to be of either @code{float}, @code{double}, or @code{long
-double} type.
-
-@comment math.h
-@comment ISO
-@deftypefn {Macro} int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
-This macro determines whether the argument @var{x} is greater than
-@var{y}.  This is equivalent to @code{(@var{x}) > (@var{y})} but no
-exception is raised if @var{x} or @var{y} are unordered.
-@end deftypefn
-
-@comment math.h
-@comment ISO
-@deftypefn {Macro} int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
-This macro determines whether the argument @var{x} is greater than or
-equal to @var{y}.  This is equivalent to @code{(@var{x}) >= (@var{y})} but no
-exception is raised if @var{x} or @var{y} are unordered.
-@end deftypefn
-
-@comment math.h
-@comment ISO
-@deftypefn {Macro} int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
-This macro determines whether the argument @var{x} is less than @var{y}.
-This is equivalent @code{(@var{x}) < (@var{y})} but no exception is raised if
-@var{x} or @var{y} are unordered.
-@end deftypefn
-
-@comment math.h
-@comment ISO
-@deftypefn {Macro} int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
-This macro determines whether the argument @var{x} is less than or equal
-to @var{y}.  This is equivalent to @code{(@var{x}) <= (@var{y})} but no
-exception is raised if @var{x} or @var{y} are unordered.
-@end deftypefn
-
-@comment math.h
-@comment ISO
-@deftypefn {Macro} int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
-This macro determines whether the argument @var{x} is less or greater
-than @var{y}.  This is equivalent to @code{(@var{x}) < (@var{y}) ||
-(@var{x}) > (@var{y})} (except that @var{x} and @var{y} are only
-evaluated once) but no exception is raised if @var{x} or @var{y} are
-unordered.
-@end deftypefn
-
-@comment math.h
-@comment ISO
-@deftypefn {Macro} int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
-This macro determines whether its arguments are unordered.
-@end deftypefn
-
-All the macros are defined in a way to ensure that both arguments are
-evaluated exactly once and so they can be used exactly like the builtin
-operators.
-
-On several platform these macros are mapped to efficient instructions
-the processor understands.  But on machines missing these functions, the
-macros above might be rather slow.  So it is best to use the builtin
-operators unless it is necessary to use unordered comparisons.
-
-@strong{Note:} There are no macros @code{isequal} or @code{isunequal}.
-These macros are not necessary since the @w{IEEE 754} standard requires
-that the comparison for equality and unequality do @emph{not} throw an
-exception if one of the arguments is an unordered value.
-
-
-@node FP Function Optimizations
-@section Is Fast Code or Small Code preferred?
-@cindex Optimization
-
-If an application uses many floating point function it is often the case
-that the costs for the function calls itselfs are not neglectable.
-Modern processor implementation often can execute the operation itself
-very fast but the call means a disturbance of the control flow.
-
-For this reason the GNU C Library provides optimizations for many of the
-frequently used math functions.  When the GNU CC is used and the user
-activates the optimizer several new inline functions and macros get
-defined.  These new functions and macros have the same names as the
-library function and so get used instead of the later.  In case of
-inline functions the compiler will decide whether it is reasonable to
-use the inline function and this decision is usually correct.
-
-For the generated code this means that no calls to the library functions
-are necessary.  This increases the speed significantly.  But the
-drawback is that the code size increases and this increase is not always
-neglectable.
-
-In cases where the inline functions and macros are not wanted the symbol
-@code{__NO_MATH_INLINES} should be defined before any system header is
-included.  This will make sure only library functions are used.  Of
-course it can be determined for each single file in the project whether
-giving this option is preferred or not.
-
+same value as @code{M_PI}.  This constant is not standard; it may have
+appeared in some old AT&T headers, and is mentioned in Stroustrup's book
+on C++.  It infringes on the user's name space, so the GNU C library
+does not define it.  Fixing programs written to expect it is simple:
+replace @code{PI} with @code{M_PI} throughout, or put @samp{-DPI=M_PI}
+on the compiler command line.
 
 @node Trig Functions
 @section Trigonometric Functions
@@ -744,10 +134,10 @@ The arguments to all of these functions are in units of radians; recall
 that pi radians equals 180 degrees.
 
 @cindex pi (trigonometric constant)
-The math library does define a symbolic constant for pi in @file{math.h}
-(@pxref{Mathematical Constants}) when BSD compliance is required
-(@pxref{Feature Test Macros}).  In case it is not possible to use this
-predefined macro one easily can define it:
+The math library normally defines @code{M_PI} to a @code{double}
+approximation of pi.  If strict ISO and/or POSIX compliance
+are requested this constant is not defined, but you can easily define it
+yourself:
 
 @smallexample
 #define M_PI 3.14159265358979323846264338327
@@ -757,7 +147,6 @@ predefined macro one easily can define it:
 You can also compute the value of pi with the expression @code{acos
 (-1.0)}.
 
-
 @comment math.h
 @comment ISO
 @deftypefun double sin (double @var{x})
@@ -784,22 +173,15 @@ radians.  The return value is in the range @code{-1} to @code{1}.
 These functions return the tangent of @var{x}, where @var{x} is given in
 radians.
 
-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 @code{errno} to @code{ERANGE} and returns
-either positive or negative @code{HUGE_VAL}.
-@end table
+singularities, @code{tan} will signal overflow.
 @end deftypefun
 
-In many applications where @code{sin} and @code{cos} are used, the value
-for the same argument of both of these functions is used at the same
-time.  Since the algorithm to compute these values is very similar for
-both functions there is an additional function which computes both values
-at the same time.
+In many applications where @code{sin} and @code{cos} are used, the sine
+and cosine of the same angle are needed at the same time.  It is more
+efficient to compute them simultaneously, so the library provides a
+function to do that.
 
 @comment math.h
 @comment GNU
@@ -811,33 +193,34 @@ cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
 radians.  Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
 the range of @code{-1} to @code{1}.
 
-This function is a GNU extension.  It should be used whenever both sine
-and cosine are needed but in portable applications there should be a
-fallback method for systems without this function.
+This function is a GNU extension.  Portable programs should be prepared
+to cope with its absence.
 @end deftypefun
 
 @cindex complex trigonometric functions
 
-The trigonometric functions are in mathematics not only defined on real
-numbers.  They can be extended to complex numbers and the @w{ISO C 9X}
-standard introduces these variants in the standard math library.
+@w{ISO C 9x} defines variants of the trig functions which work on
+complex numbers.  The GNU C library provides these functions, but they
+are only useful if your compiler supports the new complex types defined
+by the standard.
+@c Change this when gcc is fixed. -zw
+(As of this writing GCC supports complex numbers, but there are bugs in
+the implementation.)
 
 @comment complex.h
 @comment ISO
 @deftypefun {complex double} csin (complex double @var{z})
 @deftypefunx {complex float} csinf (complex float @var{z})
 @deftypefunx {complex long double} csinl (complex long double @var{z})
-These functions return the complex sine of the complex value in @var{z}.
+These functions return the complex sine of @var{z}.
 The mathematical definition of the complex sine is
 
 @ifinfo
 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
 @end ifinfo
-@iftex
 @tex
 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
 @end tex
-@end iftex
 @end deftypefun
 
 @comment complex.h
@@ -845,17 +228,15 @@ $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
 @deftypefun {complex double} ccos (complex double @var{z})
 @deftypefunx {complex float} ccosf (complex float @var{z})
 @deftypefunx {complex long double} ccosl (complex long double @var{z})
-These functions return the complex cosine of the complex value in @var{z}.
+These functions return the complex cosine of @var{z}.
 The mathematical definition of the complex cosine is
 
 @ifinfo
 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
 @end ifinfo
-@iftex
 @tex
 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
 @end tex
-@end iftex
 @end deftypefun
 
 @comment complex.h
@@ -863,17 +244,20 @@ $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
 @deftypefun {complex double} ctan (complex double @var{z})
 @deftypefunx {complex float} ctanf (complex float @var{z})
 @deftypefunx {complex long double} ctanl (complex long double @var{z})
-These functions return the complex tangent of the complex value in @var{z}.
+These functions return the complex tangent of @var{z}.
 The mathematical definition of the complex tangent is
 
 @ifinfo
-@math{tan (z) = 1/i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
+@math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
 @end ifinfo
-@iftex
 @tex
-$$\tan(z) = {1\over i} {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
+$$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
 @end tex
-@end iftex
+
+@noindent
+The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an
+integer.  @code{ctan} may signal overflow if @var{z} is too close to a
+pole.
 @end deftypefun
 
 
@@ -895,9 +279,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).
 
-@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}.
+The arc sine function is defined mathematically only
+over the domain @code{-1} to @code{1}.  If @var{x} is outside the
+domain, @code{asin} signals a domain error.
 @end deftypefun
 
 @comment math.h
@@ -910,12 +294,11 @@ 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).
 
-@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}.
+The arc cosine function is defined mathematically only
+over the domain @code{-1} to @code{1}.  If @var{x} is outside the
+domain, @code{acos} signals a domain error.
 @end deftypefun
 
-
 @comment math.h
 @comment ISO
 @deftypefun double atan (double @var{x})
@@ -924,8 +307,7 @@ over the domain @code{-1} to @code{1}.
 These functions compute the arc tangent of @var{x}---that is, the value
 whose tangent 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).
+returned is the one between @code{-pi/2} and @code{pi/2} (inclusive).
 @end deftypefun
 
 @comment math.h
@@ -933,11 +315,10 @@ returned is the one between @code{-pi/2} and @code{pi/2}
 @deftypefun double atan2 (double @var{y}, double @var{x})
 @deftypefunx float atan2f (float @var{y}, float @var{x})
 @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
-This is the two argument arc tangent function.  It is similar to computing
-the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
-are used to determine the quadrant of the result, and @var{x} is
-permitted to be zero.  The return value is given in radians and is in
-the range @code{-pi} to @code{pi}, inclusive.
+This function computes the arc tangent of @var{y}/@var{x}, but the signs
+of both arguments are used to determine the quadrant of the result, and
+@var{x} is permitted to be zero.  The return value is given in radians
+and is in the range @code{-pi} to @code{pi}, inclusive.
 
 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
@@ -946,15 +327,12 @@ converting Cartesian coordinates to polar coordinates.  (To compute the
 radial coordinate, use @code{hypot}; see @ref{Exponents and
 Logarithms}.)
 
-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.
+@c This is experimentally true.  Should it be so? -zw
+If both @var{x} and @var{y} are zero, @code{atan2} returns zero.
 @end deftypefun
 
 @cindex inverse complex trigonometric functions
-
-The inverse trigonometric functions also exist is separate versions
-which are usable with complex numbers.
+@w{ISO C 9x} defines complex versions of the inverse trig functions.
 
 @comment complex.h
 @comment ISO
@@ -962,10 +340,10 @@ which are usable with complex numbers.
 @deftypefunx {complex float} casinf (complex float @var{z})
 @deftypefunx {complex long double} casinl (complex long double @var{z})
 These functions compute the complex arc sine of @var{z}---that is, the
-value whose sine is @var{z}.  The value is in units of radians.
+value whose sine is @var{z}.  The value returned is in radians.
 
-Unlike the real version of the arc sine function @code{casin} has no
-limitation on the argument @var{z}.
+Unlike the real-valued functions, @code{casin} is defined for all
+values of @var{z}.
 @end deftypefun
 
 @comment complex.h
@@ -974,10 +352,10 @@ limitation on the argument @var{z}.
 @deftypefunx {complex float} cacosf (complex float @var{z})
 @deftypefunx {complex long double} cacosl (complex long double @var{z})
 These functions compute the complex arc cosine of @var{z}---that is, the
-value whose cosine is @var{z}.  The value is in units of radians.
+value whose cosine is @var{z}.  The value returned is in radians.
 
-Unlike the real version of the arc cosine function @code{cacos} has no
-limitation on the argument @var{z}.
+Unlike the real-valued functions, @code{cacos} is defined for all
+values of @var{z}.
 @end deftypefun
 
 
@@ -1002,11 +380,11 @@ the value whose tangent is @var{z}.  The value is in units of radians.
 @deftypefun double exp (double @var{x})
 @deftypefunx float expf (float @var{x})
 @deftypefunx {long double} expl (long double @var{x})
-These functions return the value of @code{e} (the base of natural
-logarithms) raised to power @var{x}.
+These functions compute @code{e} (the base of natural logarithms) raised
+to the power @var{x}.
 
-The function fails, and sets @code{errno} to @code{ERANGE}, if the
-magnitude of the result is too large to be representable.
+If the magnitude of the result is too large to be representable,
+@code{exp} signals overflow.
 @end deftypefun
 
 @comment math.h
@@ -1014,11 +392,8 @@ magnitude of the result is too large to be representable.
 @deftypefun double exp2 (double @var{x})
 @deftypefunx float exp2f (float @var{x})
 @deftypefunx {long double} exp2l (long double @var{x})
-These functions return the value of @code{2} raised to the power @var{x}.
+These functions compute @code{2} raised to the power @var{x}.
 Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
-
-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
@@ -1029,15 +404,11 @@ magnitude of the result is too large to be representable.
 @deftypefunx double pow10 (double @var{x})
 @deftypefunx float pow10f (float @var{x})
 @deftypefunx {long double} pow10l (long double @var{x})
-These functions return the value of @code{10} raised to the power @var{x}.
-Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
+These functions compute @code{10} raised to the power @var{x}.
+Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
 
-The function fails, and sets @code{errno} to @code{ERANGE}, if the
-magnitude of the result is too large to be representable.
-
-All these functions are GNU extensions.  The name @code{pow10} is used
-in some old code but the name @code{exp10} clearly is more in the sense
-of the ISO library designers and therefore should probably be preferred.
+These functions are GNU extensions.  The name @code{exp10} is
+preferred, since it is analogous to @code{exp} and @code{exp2}.
 @end deftypefun
 
 
@@ -1046,20 +417,13 @@ of the ISO library designers and therefore should probably be preferred.
 @deftypefun double log (double @var{x})
 @deftypefunx float logf (float @var{x})
 @deftypefunx {long double} logl (long double @var{x})
-These functions return the natural logarithm of @var{x}.  @code{exp (log
+These functions compute the natural logarithm of @var{x}.  @code{exp (log
 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
 C.
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-The argument @var{x} is negative.  The log function is defined
-mathematically to return a real result only on positive arguments.
-
-@item ERANGE
-The argument is zero.  The log of zero is not defined.
-@end table
+If @var{x} is negative, @code{log} signals a domain error.  If @var{x}
+is zero, it returns negative infinity; if @var{x} is too close to zero,
+it may signal overflow.
 @end deftypefun
 
 @comment math.h
@@ -1067,9 +431,9 @@ The argument is zero.  The log of zero is not defined.
 @deftypefun double log10 (double @var{x})
 @deftypefunx float log10f (float @var{x})
 @deftypefunx {long double} log10l (long double @var{x})
-These functions return the base-10 logarithm of @var{x}.  Except for the
-different base, it is similar to the @code{log} function.  In fact,
+These functions return the base-10 logarithm of @var{x}.
 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
+
 @end deftypefun
 
 @comment math.h
@@ -1077,8 +441,7 @@ different base, it is similar to the @code{log} function.  In fact,
 @deftypefun double log2 (double @var{x})
 @deftypefunx float log2f (float @var{x})
 @deftypefunx {long double} log2l (long double @var{x})
-These functions return the base-2 logarithm of @var{x}.  Except for the
-different base, it is similar to the @code{log} function.  In fact,
+These functions return the base-2 logarithm of @var{x}.
 @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
 @end deftypefun
 
@@ -1088,12 +451,13 @@ different base, it is similar to the @code{log} function.  In fact,
 @deftypefunx float logbf (float @var{x})
 @deftypefunx {long double} logbl (long double @var{x})
 These functions extract the exponent of @var{x} and return it as a
-signed integer value.  If @var{x} is zero, a range error may occur.
+floating-point value.  If @code{FLT_RADIX} is two, @code{logb} is equal
+to @code{floor (log2 (x))}, except it's probably faster.
 
-A special case are subnormal numbers (if supported by the floating-point
-format).  The exponent returned is not the actual value from @var{x}.
-Instead the number is first normalized as if the range of the exponent
-field is large enough.
+If @var{x} is denormalized, @code{logb} returns the exponent @var{x}
+would have if it were normalized.  If @var{x} is infinity (positive or
+negative), @code{logb} returns @math{@infinity{}}.  If @var{x} is zero,
+@code{logb} returns @math{@infinity{}}.  It does not signal.
 @end deftypefun
 
 @comment math.h
@@ -1102,17 +466,34 @@ field is large enough.
 @deftypefunx int ilogbf (float @var{x})
 @deftypefunx int ilogbl (long double @var{x})
 These functions are equivalent to the corresponding @code{logb}
-functions except that the values are returned as signed integer values.
-Since integer values cannot represent infinity and NaN, there are some
-special symbols defined to help detect these situations.
-
-@vindex FP_ILOGB0
-@vindex FP_ILOGBNAN
-@code{ilogb} returns @code{FP_ILOGB0} if @var{x} is @code{0} and it
-returns @code{FP_ILOGBNAN} if @var{x} is @code{NaN}.  These values are
-system specific and no fixed value is assigned.  More concrete, these
-values might even have the same value.  So a piece of code handling the
-result of @code{ilogb} could look like this:
+functions except that they return signed integer values.
+@end deftypefun
+
+@noindent
+Since integers cannot represent infinity and NaN, @code{ilogb} instead
+returns an integer that can't be the exponent of a normal floating-point
+number.  @file{math.h} defines constants so you can check for this.
+
+@comment math.h
+@comment ISO
+@deftypevr Macro int FP_ILOGB0
+@code{ilogb} returns this value if its argument is @code{0}.  The
+numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
+
+This macro is defined in @w{ISO C 9X}.
+@end deftypevr
+
+@comment math.h
+@comment ISO
+@deftypevr Macro int FP_ILOGBNAN
+@code{ilogb} returns this value if its argument is @code{NaN}.  The
+numeric value is either @code{INT_MIN} or @code{INT_MAX}.
+
+This macro is defined in @w{ISO C 9X}.
+@end deftypevr
+
+These values are system specific.  They might even be the same.  The
+proper way to test the result of @code{ilogb} is as follows:
 
 @smallexample
 i = ilogb (f);
@@ -1134,8 +515,6 @@ if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
   @}
 @end smallexample
 
-@end deftypefun
-
 @comment math.h
 @comment ISO
 @deftypefun double pow (double @var{base}, double @var{power})
@@ -1144,17 +523,10 @@ if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
 These are general exponentiation functions, returning @var{base} raised
 to @var{power}.
 
-@need 250
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-The argument @var{base} is negative and @var{power} is not an integral
-value.  Mathematically, the result would be a complex number in this case.
-
-@item ERANGE
-An underflow or overflow condition was detected in the result.
-@end table
+Mathematically, @code{pow} would return a complex number when @var{base}
+is negative and @var{power} is not an integral value.  @code{pow} can't
+do that, so instead it signals a domain error. @code{pow} may also
+underflow or overflow the destination type.
 @end deftypefun
 
 @cindex square root function
@@ -1165,10 +537,8 @@ An underflow or overflow condition was detected in the result.
 @deftypefunx {long double} sqrtl (long double @var{x})
 These functions return the nonnegative square root of @var{x}.
 
-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.
-@c (@pxref{csqrt})
+If @var{x} is negative, @code{sqrt} signals a domain error.
+Mathematically, it should return a complex number.
 @end deftypefun
 
 @cindex cube root function
@@ -1187,10 +557,10 @@ fail; every representable real value has a representable real cube root.
 @deftypefunx float hypotf (float @var{x}, float @var{y})
 @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
 These functions return @code{sqrt (@var{x}*@var{x} +
-@var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
+@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.)  Using this function
-instead of the direct formula is highly appreciated since the error is
+of the point (@var{x}, @var{y}) from the origin.  Using this function
+instead of the direct formula is wise, since the error is
 much smaller.  See also the function @code{cabs} in @ref{Absolute Value}.
 @end deftypefun
 
@@ -1200,7 +570,7 @@ much smaller.  See also the function @code{cabs} in @ref{Absolute Value}.
 @deftypefunx float expm1f (float @var{x})
 @deftypefunx {long double} expm1l (long double @var{x})
 These functions return 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
+They are computed in a way that is accurate even if @var{x} is
 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
 to subtraction of two numbers that are nearly equal.
 @end deftypefun
@@ -1210,39 +580,32 @@ to subtraction of two numbers that are nearly equal.
 @deftypefun double log1p (double @var{x})
 @deftypefunx float log1pf (float @var{x})
 @deftypefunx {long double} log1pl (long double @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
+These functions returns a value equivalent to @w{@code{log (1 + @var{x})}}.
+They are computed in a way that is accurate even if @var{x} is
 near zero.
 @end deftypefun
 
 @cindex complex exponentiation functions
 @cindex complex logarithm functions
 
-@w{ISO C 9X} defines variants of some of the exponentiation and
-logarithm functions.  As for the other functions handling complex
-numbers these functions are perhaps better optimized and provide better
-error checking than a direct use of the formulas of the mathematical
-definition.
+@w{ISO C 9X} defines complex variants of some of the exponentiation and
+logarithm functions.
 
 @comment complex.h
 @comment ISO
 @deftypefun {complex double} cexp (complex double @var{z})
 @deftypefunx {complex float} cexpf (complex float @var{z})
 @deftypefunx {complex long double} cexpl (complex long double @var{z})
-These functions return the value of @code{e} (the base of natural
-logarithms) raised to power of the complex value @var{z}.
-
-@noindent
+These functions return @code{e} (the base of natural
+logarithms) raised to the power of @var{z}.
 Mathematically this corresponds to the value
 
 @ifinfo
 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
 @end ifinfo
-@iftex
 @tex
-$$\exp(z) = e^z = e^{{\rm Re} z} (\cos ({\rm Im} z) + i \sin ({\rm Im} z))$$
+$$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$
 @end tex
-@end iftex
 @end deftypefun
 
 @comment complex.h
@@ -1250,21 +613,20 @@ $$\exp(z) = e^z = e^{{\rm Re} z} (\cos ({\rm Im} z) + i \sin ({\rm Im} z))$$
 @deftypefun {complex double} clog (complex double @var{z})
 @deftypefunx {complex float} clogf (complex float @var{z})
 @deftypefunx {complex long double} clogl (complex long double @var{z})
-These functions return the natural logarithm of the complex value
-@var{z}.  Unlike the real value version @code{log} and its variants,
-@code{clog} has no limit for the range of its argument @var{z}.
-
-@noindent
+These functions return the natural logarithm of @var{z}.
 Mathematically this corresponds to the value
 
 @ifinfo
 @math{log (z) = log (cabs (z)) + I * carg (z)}
 @end ifinfo
-@iftex
 @tex
-$$\log(z) = \log(|z|) + i \arg(z)$$
+$$\log(z) = \log |z| + i \arg z$$
 @end tex
-@end iftex
+
+@noindent
+@code{clog} has a pole at 0, and will signal overflow if @var{z} equals
+or is very close to 0.  It is well-defined for all other values of
+@var{z}.
 @end deftypefun
 
 
@@ -1274,22 +636,16 @@ $$\log(z) = \log(|z|) + i \arg(z)$$
 @deftypefunx {complex float} clog10f (complex float @var{z})
 @deftypefunx {complex long double} clog10l (complex long double @var{z})
 These functions return the base 10 logarithm of the complex value
-@var{z}.  Unlike the real value version @code{log} and its variants,
-@code{clog} has no limit for the range of its argument @var{z}.
-
-@noindent
-Mathematically this corresponds to the value
+@var{z}. Mathematically this corresponds to the value
 
 @ifinfo
 @math{log (z) = log10 (cabs (z)) + I * carg (z)}
 @end ifinfo
-@iftex
 @tex
-$$\log_{10}(z) = \log_{10}(|z|) + i \arg(z)$$
+$$\log_{10}(z) = \log_{10}|z| + i \arg z$$
 @end tex
-@end iftex
 
-This function is a GNU extension.
+These functions are GNU extensions.
 @end deftypefun
 
 @comment complex.h
@@ -1297,9 +653,8 @@ This function is a GNU extension.
 @deftypefun {complex double} csqrt (complex double @var{z})
 @deftypefunx {complex float} csqrtf (complex float @var{z})
 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
-These functions return the complex root of the argument @var{z}.  Unlike
-the @code{sqrt} function these functions do not have any restriction on
-the value of the argument.
+These functions return the complex square root of the argument @var{z}.  Unlike
+the real-valued functions, they are defined for all values of @var{z}.
 @end deftypefun
 
 @comment complex.h
@@ -1307,20 +662,10 @@ the value of the argument.
 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
-These functions return the complex value @var{base} raised to the power of
-@var{power}.  This is computed as
-
-@ifinfo
-@math{cpow (x, y) = cexp (y * clog (x))}
-@end ifinfo
-@iftex
-@tex
-$${\rm cpow}(x, y) = e^{y \log(x)}$$
-@end tex
-@end iftex
+These functions return @var{base} raised to the power of
+@var{power}.  This is equivalent to @w{@code{cexp (y * clog (x))}}
 @end deftypefun
 
-
 @node Hyperbolic Functions
 @section Hyperbolic Functions
 @cindex hyperbolic functions
@@ -1334,9 +679,8 @@ see @ref{Exponents and Logarithms}.
 @deftypefunx float sinhf (float @var{x})
 @deftypefunx {long double} sinhl (long double @var{x})
 These functions return the hyperbolic sine of @var{x}, 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.
+mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}.  They
+may signal overflow if @var{x} is too large.
 @end deftypefun
 
 @comment math.h
@@ -1346,8 +690,7 @@ function fails, and sets @code{errno} to @code{ERANGE}, if the value of
 @deftypefunx {long double} coshl (long double @var{x})
 These function return the hyperbolic cosine of @var{x},
 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.
+They may signal overflow if @var{x} is too large.
 @end deftypefun
 
 @comment math.h
@@ -1355,16 +698,15 @@ of @var{x} is too large; that is, if overflow occurs.
 @deftypefun double tanh (double @var{x})
 @deftypefunx float tanhf (float @var{x})
 @deftypefunx {long double} tanhl (long double @var{x})
-These functions return the hyperbolic tangent of @var{x}, whose
-mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
+These functions return the hyperbolic tangent of @var{x},
+defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
+They may signal overflow if @var{x} is too large.
 @end deftypefun
 
 @cindex hyperbolic functions
 
-There are counterparts for these hyperbolic functions which work with
-complex valued arguments.  They should always be used instead of the
-obvious mathematical formula since the implementations in the math
-library are optimized for accuracy and speed.
+There are counterparts for the hyperbolic functions which take
+complex arguments.
 
 @comment complex.h
 @comment ISO
@@ -1372,9 +714,7 @@ library are optimized for accuracy and speed.
 @deftypefunx {complex float} csinhf (complex float @var{z})
 @deftypefunx {complex long double} csinhl (complex long double @var{z})
 These functions return the complex hyperbolic sine of @var{z}, defined
-mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.  The
-function fails, and sets @code{errno} to @code{ERANGE}, if the value of
-result is too large.
+mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.
 @end deftypefun
 
 @comment complex.h
@@ -1383,9 +723,7 @@ result is too large.
 @deftypefunx {complex float} ccoshf (complex float @var{z})
 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
 These functions return the complex hyperbolic cosine of @var{z}, defined
-mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.  The
-function fails, and sets @code{errno} to @code{ERANGE}, if the value of
-result is too large.
+mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.
 @end deftypefun
 
 @comment complex.h
@@ -1393,8 +731,8 @@ result is too large.
 @deftypefun {complex double} ctanh (complex double @var{z})
 @deftypefunx {complex float} ctanhf (complex float @var{z})
 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
-These functions return the complex hyperbolic tangent of @var{z}, whose
-mathematical definition is @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
+These functions return the complex hyperbolic tangent of @var{z},
+defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
 @end deftypefun
 
 
@@ -1416,7 +754,7 @@ value whose hyperbolic sine is @var{x}.
 @deftypefunx {long double} acoshl (long double @var{x})
 These functions return the inverse hyperbolic cosine of @var{x}---the
 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
-@code{1}, @code{acosh} returns @code{HUGE_VAL}.
+@code{1}, @code{acosh} signals a domain error.
 @end deftypefun
 
 @comment math.h
@@ -1426,8 +764,8 @@ value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
 @deftypefunx {long double} atanhl (long double @var{x})
 These functions return the inverse hyperbolic tangent of @var{x}---the
 value whose hyperbolic tangent is @var{x}.  If the absolute value of
-@var{x} is greater than or equal to @code{1}, @code{atanh} returns
-@code{HUGE_VAL}.
+@var{x} is greater than @code{1}, @code{atanh} signals a domain error;
+if it is equal to 1, @code{atanh} returns infinity.
 @end deftypefun
 
 @cindex inverse complex hyperbolic functions
@@ -1448,8 +786,7 @@ These functions return the inverse complex hyperbolic sine of
 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
 These functions return the inverse complex hyperbolic cosine of
 @var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
-the real valued function @code{acosh} there is not limit for the range
-of the argument.
+the real-valued functions, there are no restrictions on the value of @var{z}.
 @end deftypefun
 
 @comment complex.h
@@ -1459,10 +796,157 @@ of the argument.
 @deftypefunx {complex long double} catanhl (complex long double @var{z})
 These functions return the inverse complex hyperbolic tangent of
 @var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
-the real valued function @code{atanh} there is not limit for the range
-of the argument.
+the real-valued functions, there are no restrictions on the value of
+@var{z}.
 @end deftypefun
 
+@node Special Functions
+@section Special Functions
+@cindex special functions
+@cindex Bessel functions
+@cindex gamma function
+
+These are some more exotic mathematical functions, which are sometimes
+useful.  Currently they only have real-valued versions.
+
+@comment math.h
+@comment SVID
+@deftypefun double erf (double @var{x})
+@deftypefunx float erff (float @var{x})
+@deftypefunx {long double} erfl (long double @var{x})
+@code{erf} returns the error function of @var{x}.  The error
+function is defined as
+@tex
+$$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
+@end smallexample
+@end ifnottex
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double erfc (double @var{x})
+@deftypefunx float erfcf (float @var{x})
+@deftypefunx {long double} erfcl (long double @var{x})
+@code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a
+fashion that avoids round-off error when @var{x} is large.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double lgamma (double @var{x})
+@deftypefunx float lgammaf (float @var{x})
+@deftypefunx {long double} lgammal (long double @var{x})
+@code{lgamma} returns the natural logarithm of the absolute value of
+the gamma function of @var{x}.  The gamma function is defined as
+@tex
+$$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
+@end smallexample
+@end ifnottex
+
+@vindex signgam
+The sign of the gamma function is stored in the global variable
+@var{signgam}, which is declared in @file{math.h}.  It is @code{1} if
+the intermediate result was positive or zero, and, @code{-1} if it was
+negative.
+
+You can compute the actual gamma function as follows:
+@smallexample
+lgam = lgamma(x);
+gam  = signgam*exp(lgam);
+@end smallexample
+
+The gamma function has singularities at the nonpositive integers.
+@code{lgamma} will raise the zero divide exception if evaluated at a
+singularity.
+@end deftypefun
+
+@comment math.h
+@comment XPG
+@deftypefun double lgamma_r (double @var{x})
+@deftypefunx float lgammaf_r (float @var{x})
+@deftypefunx {long double} lgammal_r (long double @var{x})
+@code{lgamma_r} is just like @code{lgamma}, but it stores the sign of
+the intermediate result in the variable pointed to by @var{signp}
+instead of in the @var{signgam} global.
+@end deftypefun
+
+@ignore
+@comment math.h
+@comment SVID
+@deftypefun double gamma (double @var{x})
+@deftypefunx float gammaf (float @var{x})
+@deftypefunx {long double} gammal (long double @var{x})
+??? _not_ exp(lgamma())*signgam - historical?
+@end deftypefun
+@end ignore
+
+@comment math.h
+@comment SVID
+@deftypefun double j0 (double @var{x})
+@deftypefunx float j0f (float @var{x})
+@deftypefunx {long double} j0l (long double @var{x})
+@code{j0} returns the Bessel function of the first kind of order 0 of
+@var{x}.  It may signal underflow if @var{x} is too large.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double j1 (double @var{x})
+@deftypefunx float j1f (float @var{x})
+@deftypefunx {long double} j1l (long double @var{x})
+@code{j1} returns the Bessel function of the first kind of order 1 of
+@var{x}.  It may signal underflow if @var{x} is too large.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double jn (int n, double @var{x})
+@deftypefunx float jnf (int n, float @var{x})
+@deftypefunx {long double} jnl (int n, long double @var{x})
+@code{jn} returns the Bessel function of the first kind of order
+@var{n} of @var{x}.  It may signal underflow if @var{x} is too large.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double y0 (double @var{x})
+@deftypefunx float y0f (float @var{x})
+@deftypefunx {long double} y0l (long double @var{x})
+@code{y0} returns the Bessel function of the second kind of order 0 of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{y0} signals a domain error; if it is zero,
+@code{y0} signals overflow and returns @math{-@infinity}.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double y1 (double @var{x})
+@deftypefunx float y1f (float @var{x})
+@deftypefunx {long double} y1l (long double @var{x})
+@code{y1} returns the Bessel function of the second kind of order 1 of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{y1} signals a domain error; if it is zero,
+@code{y1} signals overflow and returns @math{-@infinity}.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double yn (int n, double @var{x})
+@deftypefunx float ynf (int n, float @var{x})
+@deftypefunx {long double} ynl (int n, long double @var{x})
+@code{yn} returns the Bessel function of the second kind of order @var{n} of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{yn} signals a domain error; if it is zero,
+@code{yn} signals overflow and returns @math{-@infinity}.
+@end deftypefun
 
 @node Pseudo-Random Numbers
 @section Pseudo-Random Numbers
@@ -1472,19 +956,19 @@ of the argument.
 
 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.
+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 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 want the program to behave unpredictably.  If you want a different
+pseudo-random series each time your program runs, you must specify a
+different seed each time.  For ordinary purposes, basing the seed on the
+current time works well.
 
 You can get repeatable sequences of numbers on a particular machine type
 by specifying the same initial seed value for the random number
@@ -1493,19 +977,20 @@ 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 @w{ISO C} random number functions
-plus two other sets derived from BSD and SVID.  We recommend you use the
-standard ones, @code{rand} and @code{srand} if only a small number of
-random bits are required.  The SVID functions provide an interface which
-allows better random number generator algorithms and they return up to
-48 random bits in one calls and they also return random floating-point
-numbers if wanted.  The SVID function might not be available on some BSD
-derived systems but since they are required in the XPG they are
-available on all Unix-conformant systems.
+plus two other sets derived from BSD and SVID.  The BSD and @w{ISO C}
+functions provide identical, somewhat limited functionality.  If only a
+small number of random bits are required, we recommend you use the
+@w{ISO C} interface, @code{rand} and @code{srand}.  The SVID functions
+provide a more flexible interface, which allows better random number
+generator algorithms, provides more random bits (up to 48) per call, and
+can provide random floating-point numbers.  These functions are required
+by the XPG standard and therefore will be present in all modern Unix
+systems.
 
 @menu
-* ISO Random::       @code{rand} and friends.
-* BSD Random::       @code{random} and friends.
-* SVID Random::      @code{drand48} and friends.
+* ISO Random::                  @code{rand} and friends.
+* BSD Random::                  @code{random} and friends.
+* SVID Random::                 @code{drand48} and friends.
 @end menu
 
 @node ISO Random
@@ -1521,18 +1006,17 @@ To use these facilities, you should include the header file
 @comment stdlib.h
 @comment ISO
 @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}, which is the
-largest signed integer representable in 32 bits.  In other libraries, it
-may be as low as @code{32767}.
+The value of this macro is an integer constant representing the largest
+value the @code{rand} function can return.  In the GNU library, it is
+@code{2147483647}, 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 ISO
 @deftypefun int rand (void)
 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}.
+series.  The value ranges from @code{0} to @code{RAND_MAX}.
 @end deftypefun
 
 @comment stdlib.h
@@ -1543,31 +1027,27 @@ pseudo-random numbers.  If you call @code{rand} before a seed has been
 established with @code{srand}, it uses the value @code{1} as a default
 seed.
 
-To produce truly random numbers (not just pseudo-random), do @code{srand
-(time (0))}.
+To produce a different pseudo-random series each time your program is
+run, do @code{srand (time (0))}.
 @end deftypefun
 
-A completely broken interface was designed by the POSIX.1 committee to
-support reproducible random numbers in multi-threaded programs.
+POSIX.1 extended the C standard functions to support reproducible random
+numbers in multi-threaded programs.  However, the extension is badly
+designed and unsuitable for serious work.
 
 @comment stdlib.h
 @comment POSIX.1
 @deftypefun int rand_r (unsigned int *@var{seed})
 This function returns a random number in the range 0 to @code{RAND_MAX}
-just as @code{rand} does.  But this function does not keep an internal
-state for the RNG.  Instead the @code{unsigned int} variable pointed to
-by the argument @var{seed} is the only state.  Before the value is
-returned the state will be updated so that the next call will return a
-new number.
-
-I.e., the state of the RNG can only have as much bits as the type
-@code{unsigned int} has.  This is far too few to provide a good RNG.
-This interface is broken by design.
+just as @code{rand} does.  However, all its state is stored in the
+@var{seed} argument.  This means the RNG's state can only have as many
+bits as the type @code{unsigned int} has.  This is far too few to
+provide a good RNG.
 
-If the program requires reproducible random numbers in multi-threaded
-programs the reentrant SVID functions are probably a better choice.  But
-these functions are GNU extensions and therefore @code{rand_r}, as being
-standardized in POSIX.1, should always be kept as a default method.
+If your program requires a reentrant RNG, we recommend you use the
+reentrant GNU extensions to the SVID random number generator.  The
+POSIX.1 interface should only be used when the GNU extensions are not
+available.
 @end deftypefun
 
 
@@ -1585,24 +1065,24 @@ The prototypes for these functions are in @file{stdlib.h}.
 @comment BSD
 @deftypefun {int32_t} random (void)
 This function returns the next pseudo-random number in the sequence.
-The range of values returned is from @code{0} to @code{RAND_MAX}.
+The value returned ranges from @code{0} to @code{RAND_MAX}.
 
-@strong{Please note:} Historically this function returned a @code{long
-int} value.  But with the appearance of 64bit machines this could lead
-to severe compatibility problems and therefore the type now explicitly
-limits the return value to 32bit.
+@strong{Note:} Historically this function returned a @code{long
+int} value.  On 64bit systems @code{long int} would have been larger
+than programs expected, so @code{random} is now defined to return
+exactly 32 bits.
 @end deftypefun
 
 @comment stdlib.h
 @comment BSD
 @deftypefun void srandom (unsigned int @var{seed})
-The @code{srandom} function sets the seed for the current random number
-state based on the integer @var{seed}.  If you supply a @var{seed} value
+The @code{srandom} function sets the state of the random number
+generator based on the integer @var{seed}.  If you supply a @var{seed} value
 of @code{1}, this will cause @code{random} to reproduce the default set
 of random numbers.
 
-To produce truly random numbers (not just pseudo-random), do
-@code{srandom (time (0))}.
+To produce a different set of pseudo-random numbers each time your
+program runs, do @code{srandom (time (0))}.
 @end deftypefun
 
 @comment stdlib.h
@@ -1610,9 +1090,9 @@ To produce truly random numbers (not just pseudo-random), do
 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
 The @code{initstate} function is used to initialize the random number
 generator state.  The argument @var{state} is an array of @var{size}
-bytes, used to hold the state information.  The size must be at least 8
-bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
-the @var{state} array, the better.
+bytes, used to hold the state information.  It is initialized based on
+@var{seed}.  The size must be between 8 and 256 bytes, and should be a
+power of two.  The bigger the @var{state} array, the better.
 
 The return value is the previous value of the state information array.
 You can use this value later as an argument to @code{setstate} to
@@ -1631,13 +1111,12 @@ You can use this value later as an argument to @code{setstate} to
 restore that state.
 @end deftypefun
 
-
 @node SVID Random
 @subsection SVID Random Number Function
 
 The C library on SVID systems contains yet another kind of random number
 generator functions.  They use a state of 48 bits of data.  The user can
-choose among a collection of functions which all return the random bits
+choose among a collection of functions which return the random bits
 in different forms.
 
 Generally there are two kinds of functions: those which use a state of
@@ -1973,3 +1452,37 @@ If the return value is non-negative the function call succeeded.
 This function is a GNU extension and should not be used in portable
 programs.
 @end deftypefun
+
+@node FP Function Optimizations
+@section Is Fast Code or Small Code preferred?
+@cindex Optimization
+
+If an application uses many floating point function it is often the case
+that the costs for the function calls itselfs are not neglectable.
+Modern processor implementation often can execute the operation itself
+very fast but the call means a disturbance of the control flow.
+
+For this reason the GNU C Library provides optimizations for many of the
+frequently used math functions.  When the GNU CC is used and the user
+activates the optimizer several new inline functions and macros get
+defined.  These new functions and macros have the same names as the
+library function and so get used instead of the later.  In case of
+inline functions the compiler will decide whether it is reasonable to
+use the inline function and this decision is usually correct.
+
+For the generated code this means that no calls to the library functions
+are necessary.  This increases the speed significantly.  But the
+drawback is that the code size increases and this increase is not always
+neglectable.
+
+In cases where the inline functions and macros are not wanted the symbol
+@code{__NO_MATH_INLINES} should be defined before any system header is
+included.  This will make sure only library functions are used.  Of
+course it can be determined for each single file in the project whether
+giving this option is preferred or not.
+
+Not all hardware implements the entire @w{IEEE 754} standard, or if it
+does, there may be a substantial performance penalty for using some of
+its features.  For example, enabling traps on some processors forces
+the FPU to run unpipelined, which more than doubles calculation time.
+@c ***Add explanation of -lieee, -mieee.