1 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 ‘math.h’.

All of the functions that operate on floating-point numbers accept arguments and return results of type double. In the future, there may be additional functions that operate on float and long double values. For example, cosf and cosl would be versions of the cos function that operate on float and long double arguments, respectively. In the meantime, you should avoid using these names yourself. @xref{Reserved Names}.

1.1 Domain and Range Errors

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 acos function is defined over the domain between -1 and 1. If you pass an argument to one of these functions that is outside the domain over which it is defined, the function sets errno to EDOM to indicate a domain error. On machines that support IEEE floating point, functions reporting error 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.

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 errno to ERANGE to indicate a range error, and returns a particular very large value (named by the macro HUGE_VAL) or its negation (- HUGE_VAL).

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

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

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 SIGFPE signals generated within these functions. (@xref{Signal Handling}, for more information about signals.)

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.

For more information about floating-point representations and limits, see @ref{Floating Point Parameters}. In particular, the macro DBL_MAX might be more appropriate than HUGE_VAL for many uses other than testing for an error in a mathematical function.

1.2 Trigonometric Functions

These are the familiar sin, cos, and tan functions. The arguments to all of these functions are in units of radians; recall that pi radians equals 180 degrees.

The math library doesn’t define a symbolic constant for pi, but you can define your own if you need one:

#define PI 3.14159265358979323846264338327

You can also compute the value of pi with the expression acos (-1.0).

Function: double sin (double x)

This function returns the sine of x, where x is given in radians. The return value is in the range -1 to 1.

Function: double cos (double x)

This function returns the cosine of x, where x is given in radians. The return value is in the range -1 to 1.

Function: double tan (double x)

This function returns the tangent of x, where x is given in radians.

The following errno error conditions are defined for this function:

ERANGE

Mathematically, the tangent function has singularities at odd multiples of pi/2. If the argument x is too close to one of these singularities, tan sets errno to ERANGE and returns either positive or negative HUGE_VAL.

1.3 Inverse Trigonometric 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.

Function: double asin (double x)

This function computes the arc sine of x—that is, the value whose sine is x. The value is in units of radians. Mathematically, there are infinitely many such values; the one actually returned is the one between -pi/2 and pi/2 (inclusive).

asin fails, and sets errno to EDOM, if x is out of range. The arc sine function is defined mathematically only over the domain -1 to 1.

Function: double acos (double x)

This function computes the arc cosine of x—that is, the value whose cosine is x. The value is in units of radians. Mathematically, there are infinitely many such values; the one actually returned is the one between 0 and pi (inclusive).

acos fails, and sets errno to EDOM, if x is out of range. The arc cosine function is defined mathematically only over the domain -1 to 1.

Function: double atan (double x)

This function computes the arc tangent of x—that is, the value whose tangent is x. The value is in units of radians. Mathematically, there are infinitely many such values; the one actually returned is the one between -pi/2 and pi/2 (inclusive).

Function: double atan2 (double y, double x)

This is the two argument arc tangent function. It is similar to computing the arc tangent of y/x, except that the signs of both arguments are used to determine the quadrant of the result, and x is permitted to be zero. The return value is given in radians and is in the range -pi to pi, inclusive.

If x and y are coordinates of a point in the plane, atan2 returns the signed angle between the line from the origin to that point and the x-axis. Thus, atan2 is useful for converting Cartesian coordinates to polar coordinates. (To compute the radial coordinate, use hypot; see Exponentiation and Logarithms.)

The function atan2 sets errno to EDOM if both x and y are zero; the return value is not defined in this case.

1.4 Exponentiation and Logarithms

Function: double exp (double x)

The exp function returns the value of e (the base of natural logarithms) raised to power x.

The function fails, and sets errno to ERANGE, if the magnitude of the result is too large to be representable.

Function: double log (double x)

This function returns the natural logarithm of x. exp (log (x)) equals x, exactly in mathematics and approximately in C.

The following errno error conditions are defined for this function:

EDOM

The argument x is negative. The log function is defined mathematically to return a real result only on positive arguments.

ERANGE

The argument is zero. The log of zero is not defined.

Function: double log10 (double x)

This function returns the base-10 logarithm of x. Except for the different base, it is similar to the log function. In fact, log10 (x) equals log (x) / log (10).

Function: double pow (double base, double power)

This is a general exponentiation function, returning base raised to power.

The following errno error conditions are defined for this function:

EDOM

The argument base is negative and power is not an integral value. Mathematically, the result would be a complex number in this case.

ERANGE

An underflow or overflow condition was detected in the result.

Function: double sqrt (double x)

This function returns the nonnegative square root of x.

The sqrt function fails, and sets errno to EDOM, if x is negative. Mathematically, the square root would be a complex number.

Function: double cbrt (double x)

This function returns the cube root of x. This function cannot fail; every representable real value has a representable real cube root.

Function: double hypot (double x, double y)

The hypot function returns sqrt (x*x + y*y). (This is the length of the hypotenuse of a right triangle with sides of length x and y, or the distance of the point (x, y) from the origin.) See also the function cabs in @ref{Absolute Value}.

Function: double expm1 (double x)

This function returns a value equivalent to exp (x) - 1. It is computed in a way that is accurate even if the value of x is near zero—a case where exp (x) - 1 would be inaccurate due to subtraction of two numbers that are nearly equal.

Function: double log1p (double x)

This function returns a value equivalent to log (1 + x). It is computed in a way that is accurate even if the value of x is near zero.

1.5 Hyperbolic Functions

The functions in this section are related to the exponential functions; see Exponentiation and Logarithms.

Function: double sinh (double x)

The sinh function returns the hyperbolic sine of x, defined mathematically as exp (x) - exp (-x) / 2. The function fails, and sets errno to ERANGE, if the value of x is too large; that is, if overflow occurs.

Function: double cosh (double x)

The cosh function returns the hyperbolic cosine of x, defined mathematically as exp (x) + exp (-x) / 2. The function fails, and sets errno to ERANGE, if the value of x is too large; that is, if overflow occurs.

Function: double tanh (double x)

This function returns the hyperbolic tangent of x, whose mathematical definition is sinh (x) / cosh (x).

Function: double asinh (double x)

This function returns the inverse hyperbolic sine of x—the value whose hyperbolic sine is x.

Function: double acosh (double x)

This function returns the inverse hyperbolic cosine of x—the value whose hyperbolic cosine is x. If x is less than 1, acosh returns HUGE_VAL.

Function: double atanh (double x)

This function returns the inverse hyperbolic tangent of x—the value whose hyperbolic tangent is x. If the absolute value of x is greater than or equal to 1, atanh returns HUGE_VAL.

1.6 Pseudo-Random Numbers

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 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 exactly the same from one run to the next. This is because the initial seed is always the same. This is convenient when you are debugging a program, but it is unhelpful if you want the program to behave unpredictably. If you want truly random numbers, not just pseudo-random, specify a seed based on the current time.

You can get repeatable sequences of numbers on a particular machine type by specifying the same initial seed value for the random number generator. There is no standard meaning for a particular seed value; the same seed, used in different C libraries or on different CPU types, will give you different random numbers.

The GNU library supports the standard ANSI C random number functions plus another set derived from BSD. We recommend you use the standard ones, rand and srand.

1.6.1 ANSI C Random Number Functions

This section describes the random number functions that are part of the ANSI C standard.

To use these facilities, you should include the header file ‘stdlib.h’ in your program.

Macro: int RAND_MAX

The value of this macro is an integer constant expression that represents the maximum possible value returned by the rand function. In the GNU library, it is 037777777, which is the largest signed integer representable in 32 bits. In other libraries, it may be as low as 32767.

Function: int rand ()

The rand function returns the next pseudo-random number in the series. The value is in the range from 0 to RAND_MAX.

Function: void srand (unsigned int seed)

This function establishes seed as the seed for a new series of pseudo-random numbers. If you call rand before a seed has been established with srand, it uses the value 1 as a default seed.

To produce truly random numbers (not just pseudo-random), do srand (time (0)).

1.6.2 BSD Random Number Functions

This section describes a set of random number generation functions that are derived from BSD. There is no advantage to using these functions with the GNU C library; we support them for BSD compatibility only.

The prototypes for these functions are in ‘stdlib.h’.

Function: long int random ()

This function returns the next pseudo-random number in the sequence. The range of values returned is from 0 to RAND_MAX.

Function: void srandom (unsigned int seed)

The srandom function sets the seed for the current random number state based on the integer seed. If you supply a seed value of 1, this will cause random to reproduce the default set of random numbers.

To produce truly random numbers (not just pseudo-random), do srandom (time (0)).

Function: void * initstate (unsigned int seed, void *state, size_t size)

The initstate function is used to initialize the random number generator state. The argument state is an array of 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 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 setstate to restore that state.

Function: void * setstate (void *state)

The setstate function restores the random number state information state. The argument must have been the result of a previous call to initstate or setstate.

The return value is the previous value of the state information array. You can use thise value later as an argument to setstate to restore that state.

About This Document

This document was generated on March 29, 2022 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on March 29, 2022 using texi2html 5.0.