library_17.html

Linux程序员的工作手册

<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - Mathematics</TITLE>
<P>Go to the <A HREF="library_16.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html">previous</A>, <A HREF="library_18.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_18.html">next</A> section.<P>
<H1><A NAME="SEC290" HREF="library_toc.html#SEC290" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC290">Mathematics</A></H1>
<P>
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
<TT>`math.h'</TT>.
<A NAME="IDX1246"></A>
<P>
All of the functions that operate on floating-point numbers accept
arguments and return results of type <CODE>double</CODE>.  In the future,
there may be additional functions that operate on <CODE>float</CODE> and
<CODE>long double</CODE> values.  For example, <CODE>cosf</CODE> and <CODE>cosl</CODE>
would be versions of the <CODE>cos</CODE> function that operate on
<CODE>float</CODE> and <CODE>long double</CODE> arguments, respectively.  In the
meantime, you should avoid using these names yourself.  See section <A HREF="library_1.html#SEC11" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_1.html#SEC11">Reserved Names</A>.
<P>
<H2><A NAME="SEC291" HREF="library_toc.html#SEC291" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC291">Domain and Range Errors</A></H2>
<A NAME="IDX1247"></A>
<P>
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</CODE> function is defined over the domain between <CODE>-1</CODE> and
<CODE>1</CODE>.  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</CODE> to <CODE>EDOM</CODE> to indicate a <DFN>domain error</DFN>.  On
machines that support IEEE floating point, functions reporting error
<CODE>EDOM</CODE> also return a NaN.
<P>
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.
<A NAME="IDX1248"></A>
<P>
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</CODE> to <CODE>ERANGE</CODE> to indicate a <DFN>range error</DFN>, and
returns a particular very large value (named by the macro
<CODE>HUGE_VAL</CODE>) or its negation (<CODE>- HUGE_VAL</CODE>).
<P>
If the magnitude of the result is too small, a value of zero is returned
instead.  In this case, <CODE>errno</CODE> might or might not be
set to <CODE>ERANGE</CODE>.
<P>
The only completely reliable way to check for domain and range errors is
to set <CODE>errno</CODE> to <CODE>0</CODE> before you call the mathematical function 
and test <CODE>errno</CODE> afterward.  As a consequence of this use of 
<CODE>errno</CODE>, use of the mathematical functions is not reentrant if you
check for errors.
<P>
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</CODE> signals generated within these functions.  (See section <A HREF="library_21.html#SEC330" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC330">Signal Handling</A>, for more information about signals.)
<P>
<A NAME="IDX1249"></A>
<U>Macro:</U> double <B>HUGE_VAL</B><P>
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.
<P>
The value of this macro is used as the return value from various 
mathematical functions in overflow situations.
<P>
For more information about floating-point representations and limits,
see section <A HREF="library_28.html#SEC489" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_28.html#SEC489">Floating Point Parameters</A>.  In particular, the macro
<CODE>DBL_MAX</CODE> might be more appropriate than <CODE>HUGE_VAL</CODE> for many
uses other than testing for an error in a mathematical function.
<P>
<A NAME="IDX1250"></A>
<H2><A NAME="SEC292" HREF="library_toc.html#SEC292" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC292">Trigonometric Functions</A></H2>
<P>
These are the familiar <CODE>sin</CODE>, <CODE>cos</CODE>, and <CODE>tan</CODE> functions.
The arguments to all of these functions are in units of radians; recall
that pi radians equals 180 degrees.
<A NAME="IDX1251"></A>
<P>
The math library doesn't define a symbolic constant for pi, but you can
define your own if you need one:
<P>
<PRE>
#define PI 3.14159265358979323846264338327
</PRE>
<P>
You can also compute the value of pi with the expression <CODE>acos
(-1.0)</CODE>.
<P>
<A NAME="IDX1252"></A>
<U>Function:</U> double <B>sin</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the sine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians.  The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
<P>
<A NAME="IDX1253"></A>
<U>Function:</U> double <B>cos</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the cosine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians.  The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
<P>
<A NAME="IDX1254"></A>
<U>Function:</U> double <B>tan</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the tangent of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>ERANGE</CODE>
<DD>Mathematically, the tangent function has singularities at odd multiples
of pi/2.  If the argument <VAR>x</VAR> is too close to one of these
singularities, <CODE>tan</CODE> sets <CODE>errno</CODE> to <CODE>ERANGE</CODE> and returns
either positive or negative <CODE>HUGE_VAL</CODE>.
</DL>
<P>
<A NAME="IDX1255"></A>
<H2><A NAME="SEC293" HREF="library_toc.html#SEC293" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC293">Inverse Trigonometric Functions</A></H2>
<P>
These are the usual arc sine, arc cosine and arc tangent functions,
which are the inverses of the sine, cosine and tangent functions,
respectively.
<P>
<A NAME="IDX1256"></A>
<U>Function:</U> double <B>asin</B> <I>(double <VAR>x</VAR>)</I><P>
This function computes the arc sine of <VAR>x</VAR>---that is, the value whose
sine is <VAR>x</VAR>.  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</CODE> and <CODE>pi/2</CODE> (inclusive).
<P>
<CODE>asin</CODE> fails, and sets <CODE>errno</CODE> to <CODE>EDOM</CODE>, if <VAR>x</VAR> is
out of range.  The arc sine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>.
<P>
<A NAME="IDX1257"></A>
<U>Function:</U> double <B>acos</B> <I>(double <VAR>x</VAR>)</I><P>
This function computes the arc cosine of <VAR>x</VAR>---that is, the value
whose cosine is <VAR>x</VAR>.  The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between <CODE>0</CODE> and <CODE>pi</CODE> (inclusive).
<P>
<CODE>acos</CODE> fails, and sets <CODE>errno</CODE> to <CODE>EDOM</CODE>, if <VAR>x</VAR> is
out of range.  The arc cosine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>.
<P>
<A NAME="IDX1258"></A>
<U>Function:</U> double <B>atan</B> <I>(double <VAR>x</VAR>)</I><P>
This function computes the arc tangent of <VAR>x</VAR>---that is, the value
whose tangent is <VAR>x</VAR>.  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</CODE> and <CODE>pi/2</CODE>
(inclusive).
<P>
<A NAME="IDX1259"></A>
<U>Function:</U> double <B>atan2</B> <I>(double <VAR>y</VAR>, double <VAR>x</VAR>)</I><P>
This is the two argument arc tangent function.  It is similar to computing
the arc tangent of <VAR>y</VAR>/<VAR>x</VAR>, except that the signs of both arguments
are used to determine the quadrant of the result, and <VAR>x</VAR> is
permitted to be zero.  The return value is given in radians and is in
the range <CODE>-pi</CODE> to <CODE>pi</CODE>, inclusive.
<P>
If <VAR>x</VAR> and <VAR>y</VAR> are coordinates of a point in the plane,
<CODE>atan2</CODE> returns the signed angle between the line from the origin
to that point and the x-axis.  Thus, <CODE>atan2</CODE> is useful for
converting Cartesian coordinates to polar coordinates.  (To compute the
radial coordinate, use <CODE>hypot</CODE>; see section <A HREF="library_17.html#SEC294" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_17.html#SEC294">Exponentiation and Logarithms</A>.)
<P>
The function <CODE>atan2</CODE> sets <CODE>errno</CODE> to <CODE>EDOM</CODE> if both
<VAR>x</VAR> and <VAR>y</VAR> are zero; the return value is not defined in this
case.
<P>
<A NAME="IDX1260"></A>
<A NAME="IDX1261"></A>
<A NAME="IDX1262"></A>
<H2><A NAME="SEC294" HREF="library_toc.html#SEC294" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC294">Exponentiation and Logarithms</A></H2>
<P>
<A NAME="IDX1263"></A>
<U>Function:</U> double <B>exp</B> <I>(double <VAR>x</VAR>)</I><P>
The <CODE>exp</CODE> function returns the value of e (the base of natural
logarithms) raised to power <VAR>x</VAR>.
<P>
The function fails, and sets <CODE>errno</CODE> to <CODE>ERANGE</CODE>, if the
magnitude of the result is too large to be representable.
<P>
<A NAME="IDX1264"></A>
<U>Function:</U> double <B>log</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the natural logarithm of <VAR>x</VAR>.  <CODE>exp (log
(<VAR>x</VAR>))</CODE> equals <VAR>x</VAR>, exactly in mathematics and approximately in
C.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EDOM</CODE>
<DD>The argument <VAR>x</VAR> is negative.  The log function is defined
mathematically to return a real result only on positive arguments.
<P>
<DT><CODE>ERANGE</CODE>
<DD>The argument is zero.  The log of zero is not defined.
</DL>
<P>
<A NAME="IDX1265"></A>
<U>Function:</U> double <B>log10</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the base-10 logarithm of <VAR>x</VAR>.  Except for the
different base, it is similar to the <CODE>log</CODE> function.  In fact,
<CODE>log10 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (10)</CODE>.
<P>