updated nodes and xrefs.

[kopensolaris-gnu/glibc.git] / manual / math.texi

@node Mathematics, Arithmetic, Consistency Checking, Top
@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}.
@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.

@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.
@end menu

@node Domain and Range Errors, Not a Number,  , Mathematics
@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{-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}.

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.

@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.

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.

@comment math.h
@comment ANSI
@deftypevr Macro double HUGE_VAL
An expression representing a particular very large number.  On machines
that use IEEE 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 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, Trigonometric Functions, Domain and Range Errors, Mathematics
@section ``Not a Number'' Values
@cindex NAN
@cindex not a number
@cindex IEEE floating point

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, Inverse Trigonometric Functions, Not a Number, Mathematics
@section Trigonometric Functions
@cindex trigonometric functions

These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
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 doesn't define a symbolic constant for pi, but you can
define your own if you need one:

@example
#define PI 3.14159265358979323846264338327
@end example

@noindent
You can also compute the value of pi with the expression @code{acos
(-1.0)}.


@comment math.h
@comment ANSI
@deftypefun double sin (double @var{x})
This function returns the sine of @var{x}, where @var{x} is given in
radians.  The return value is in the range @code{-1} to @code{1}.
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double cos (double @var{x})
This function returns the cosine of @var{x}, where @var{x} is given in
radians.  The return value is in the range @code{-1} to @code{1}.
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double tan (double @var{x})
This function returns 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 this error condition and returns either positive or
negative @code{HUGE_VAL}.
@end table
@end deftypefun


@node Inverse Trigonometric Functions, Exponentiation and Logarithms, Trigonometric Functions, Mathematics
@section Inverse Trigonometric Functions
@cindex inverse trigonmetric functions

These are the usual arc sine, arc cosine and arc tangent functions,
which are the inverses of the sine, cosine and tangent functions,
respectively.

@comment math.h
@comment ANSI
@deftypefun double asin (double @var{x})
This function computes the arc sine of @var{x}---that is, the value whose
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
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double acos (double @var{x})
This function computes the arc cosine of @var{x}---that is, the value
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
@end deftypefun


@comment math.h
@comment ANSI
@deftypefun double atan (double @var{x})
This function computes 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).
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double atan2 (double @var{y}, 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.

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
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
@end deftypefun


@node Exponentiation and Logarithms, Hyperbolic Functions, Inverse Trigonometric Functions, Mathematics
@section Exponentiation and Logarithms
@cindex exponentiation functions
@cindex power functions
@cindex logarithm functions

@comment math.h
@comment ANSI
@deftypefun double exp (double @var{x})
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
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double log (double @var{x})
This function returns 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 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}.

@item ERANGE
The result of the function on an argument of zero is not defined.
@end table
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double log10 (double @var{x})
This function returns the base-10 logarithm of @var{x}.  Except for the
different base, it is similar to the @code{log} function.  In fact,
@code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double pow (double @var{base}, double @var{power})
This is a general exponentiation function, returning @var{base} raised
to @var{power}.

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
@end deftypefun

@cindex square root function
@comment math.h
@comment ANSI
@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
@end deftypefun

@cindex cube root function
@comment math.h
@comment GNU
@deftypefun double cbrt (double @var{x})
This function returns the cube root of @var{x}.
@end deftypefun

@comment math.h
@comment GNU
@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.)
@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
@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
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

@comment math.h
@comment GNU
@deftypefun double log1p (double @var{x})
This function returns a value equivalent to @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

@node Hyperbolic Functions, Pseudo-Random Numbers, Exponentiation and Logarithms, Mathematics
@section Hyperbolic Functions
@cindex hyperbolic functions

The functions in this section are related to the exponential functions;
see @ref{Exponentiation 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
@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
@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})}.
@end deftypefun

@cindex inverse hyperbolic functions

@comment math.h
@comment GNU
@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
@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
@code{1}, @code{acosh} returns @code{HUGE_VAL}.
@end deftypefun

@comment math.h
@comment GNU
@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
@var{x} is greater than or equal to @code{1}, @code{atanh} returns
@code{HUGE_VAL}.
@end deftypefun

@node Pseudo-Random Numbers, Absolute Value, Hyperbolic Functions, Mathematics
@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.


@menu
* ANSI C Random Number Functions::  @code{rand} and friends.
* BSD Random Number Functions::  @code{random} and friends.
@end menu

@node ANSI C Random Number Functions, BSD Random Number Functions,  , Pseudo-Random Numbers
@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}.

To use these facilities, you should include the header file
@file{stdlib.h} in your program.
@pindex stdlib.h

@comment stdlib.h
@comment ANSI
@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}.
@end deftypevr

@comment stdlib.h
@comment ANSI
@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}.
@end deftypefun

@comment stdlib.h
@comment ANSI
@deftypefun void srand (unsigned int @var{seed})
This function establishes @var{seed} as the seed for a new series of
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))}.
@end deftypefun

@node BSD Random Number Functions,  , ANSI C Random Number Functions, Pseudo-Random Numbers
@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.

The prototypes for these functions are in @file{stdlib.h}.
@pindex stdlib.h

@comment stdlib.h
@comment BSD
@deftypefun {long int} 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}.
@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
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))}.
@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})
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.

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
restore that state.
@end deftypefun

@comment stdlib.h
@comment BSD
@deftypefun {void *} setstate (void *@var{state})
The @code{setstate} function restores the random number state
information @var{state}.  The argument must have been the result of
a previous call to @var{initstate} or @var{setstate}.  

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,  , Pseudo-Random Numbers, Mathematics
@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}.