math.texi

一个C源代码分析器

@node Mathematics, Arithmetic, Low-Level Terminal Interface, 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 the future,
there may be additional functions that operate on @code{float} and
@code{long double} values.  For example, @code{cosf} and @code{cosl}
would be versions of the @code{cos} function that operate on
@code{float} and @code{long double} arguments, respectively.  In the
meantime, you should avoid using these names yourself.  @xref{Reserved
Names}.

@menu
* Domain and Range Errors::     Detecting overflow conditions and the like.
* Trig Functions::              Sine, cosine, and tangent.
* Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
* Exponents and Logarithms::    Also includes square root.
* Hyperbolic Functions::        Hyperbolic sine and friends.
* Pseudo-Random Numbers::       Functions for generating pseudo-random
				 numbers.
@end menu

@node Domain and Range Errors
@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 sets
@code{errno} to @code{EDOM} to indicate a @dfn{domain error}.  On
machines that support IEEE floating point, functions reporting error
@code{EDOM} also return a NaN.

Some of these functions are defined mathematically to result in a
complex value over parts of their domains.  The most familiar example of
this is taking the square root of a negative number.  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 (@w{@code{- HUGE_VAL}}).

If the magnitude of the result is too small, a value of zero is returned
instead.  In this case, @code{errno} might or might not be
set to @code{ERANGE}.

The only completely reliable way to check for domain and range errors is
to set @code{errno} to @code{0} before you call the mathematical function 
and test @code{errno} afterward.  As a consequence of this use of 
@code{errno}, use of the mathematical functions is not reentrant if you
check for errors.

@c !!! this isn't always true at the moment....
None of the mathematical functions ever generates signals as a result of
domain or range errors.  In particular, this means that you won't see
@code{SIGFPE} signals generated within these functions.  (@xref{Signal
Handling}, for more information about signals.)

@comment math.h
@comment ANSI
@deftypevr Macro double HUGE_VAL
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,
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 Trig Functions
@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:

@smallexample
#define PI 3.14159265358979323846264338327
@end smallexample

@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 @code{errno} to @code{ERANGE} and returns
either positive or negative @code{HUGE_VAL}.
@end table
@end deftypefun


@node Inverse Trig Functions
@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).

@code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
out of range.  The arc sine function is defined mathematically only
over the domain @code{-1} to @code{1}.
@end deftypefun

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

@code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
out of range.  The arc cosine function is defined mathematically only
over the domain @code{-1} to @code{1}.
@end deftypefun


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


@node Exponents and Logarithms
@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 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
@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 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
@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