Fix configuration list and configure options.
[kopensolaris-gnu/glibc.git] / manual / math.texi
1 @node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
2 @chapter Mathematics
3
4 This chapter contains information about functions for performing
5 mathematical computations, such as trigonometric functions.  Most of
6 these functions have prototypes declared in the header file
7 @file{math.h}.
8 @pindex math.h
9
10 All of the functions that operate on floating-point numbers accept
11 arguments and return results of type @code{double}.  In future revisions
12 of the ANSI C standard, additional functions may be added that operate
13 on @code{float} and @code{long double} values.  For example, @code{cosf}
14 and @code{cosl} would be versions of the @code{cos} function that
15 operate on @code{float} and @code{long double} arguments, respectively.
16 In the meantime, you should avoid using these names yourself.
17 @xref{Reserved Names}.
18
19 @strong{Incomplete:}  This chapter doesn't have any examples.
20
21 @menu
22 * Domain and Range Errors::     How overflow conditions and the like
23                                  are reported.
24 * Not a Number::                Making NANs and testing for NANs.
25 * Trig Functions::              Sine, cosine, and tangent.
26 * Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
27 * Exponents and Logarithms::    Also includes square root.
28 * Hyperbolic Functions::        Hyperbolic sine and friends.
29 * Pseudo-Random Numbers::       Functions for generating pseudo-random
30                                  numbers.
31 * Absolute Value::              Absolute value functions.
32 @end menu
33
34 @node Domain and Range Errors
35 @section Domain and Range Errors
36
37 @cindex domain error
38 Many of the functions listed in this chapter are defined mathematically
39 over a domain that is only a subset of real numbers.  For example, the
40 @code{acos} function is defined over the domain between @code{-1} and
41 @code{1}.  If you pass an argument to one of these functions that is
42 outside the domain over which it is defined, the function returns
43 an unspecified value and sets @code{errno} to @code{EDOM} to indicate
44 a @dfn{domain error}.
45
46 Some of these functions are defined mathematically to result in a
47 complex value over parts of their domains.  The most familiar example of
48 this is taking the square root of a negative number.  Since the C
49 language has no support for complex numbers, this is considered a
50 domain error.
51
52 @cindex range error
53 A related problem is that the mathematical result of a function may not
54 be representable as a floating point number.  If magnitude of the
55 correct result is too large to be represented, the function sets
56 @code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
57 returns a particular very large value (named by the macro
58 @code{HUGE_VAL}) or its negation.
59
60 If the magnitude of the result is too small, a value of zero is returned
61 instead.  In this case, @code{errno} might or might not be
62 set to @code{ERANGE}.
63
64 None of the mathematical functions ever generates signals as a result of
65 domain or range errors.  In particular, this means that you won't see
66 @code{SIGFPE} signals generated within these functions.  (@xref{Signal
67 Handling}, for more information about signals.)
68
69 The only completely reliable way to check for domain and range errors is
70 to set @code{errno} to @code{0} before you call the mathematical function 
71 and test @code{errno} afterward.  As a consequence of this use of 
72 @code{errno}, use of the mathematical functions is not reentrant if you
73 check for errors.
74
75 @comment math.h
76 @comment ANSI
77 @deftypevr Macro double HUGE_VAL
78 An expression representing a particular very large number.  On machines
79 that use IEEE floating point format, the value is ``infinity''.  On
80 other machines, it's typically the largest positive number that can be
81 represented.
82
83 The value of this macro is used as the return value from various 
84 mathematical functions in overflow situations.
85 @end deftypevr
86
87 For more information about floating-point representations and limits,
88 @xref{Floating-Point Limits}.  In particular, the macro @code{DBL_MAX}
89 might be more appropriate than @code{HUGE_VAL} for many uses.
90
91 @node Not a Number
92 @section ``Not a Number'' Values
93 @cindex NAN
94 @cindex not a number
95 @cindex IEEE floating point
96
97 The IEEE floating point format used by most modern computers supports
98 values that are ``not a number''.  These values are called @dfn{NANs}.
99 ``Not a number'' values result from certain operations which have no
100 meaningful numeric result, such as zero divided by zero or infinity
101 divided by infinity.
102
103 One noteworthy property of NANs is that they are not equal to
104 themselves.  Thus, @code{x == x} can be 0 if the value of @code{x} is a
105 NAN.  In fact, this is the way to test whether a value is a NAN or not:
106 if it is not equal to itself, then it is a NAN.
107
108 Almost any arithmetic operation in which one argument is a NAN returns
109 a NAN.
110
111 @comment math.h
112 @comment GNU
113 @deftypevr Macro double NAN
114 An expression representing a value which is ``not a number''.  This
115 macro is a GNU extension, available only on machines that support ``not
116 a number'' values---that is to say, on all machines that support IEEE
117 floating point.
118
119 You can use @samp{#ifdef NAN} to test whether the machine supports NaNs.
120 (Of course, you must arrange for GNU extensions to be visible,
121 such as by defining @code{_GNU_SOURCE}.)
122 @end deftypevr
123
124 @node Trig Functions
125 @section Trigonometric Functions
126 @cindex trigonometric functions
127
128 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
129 The arguments to all of these functions are in units of radians; recall
130 that pi radians equals 180 degrees.
131
132 @cindex pi (trigonometric constant)
133 The math library doesn't define a symbolic constant for pi, but you can
134 define your own if you need one:
135
136 @example
137 #define PI 3.14159265358979323846264338327
138 @end example
139
140 @noindent
141 You can also compute the value of pi with the expression @code{acos
142 (-1.0)}.
143
144
145 @comment math.h
146 @comment ANSI
147 @deftypefun double sin (double @var{x})
148 This function returns the sine of @var{x}, where @var{x} is given in
149 radians.  The return value is in the range @code{-1} to @code{1}.
150 @end deftypefun
151
152 @comment math.h
153 @comment ANSI
154 @deftypefun double cos (double @var{x})
155 This function returns the cosine of @var{x}, where @var{x} is given in
156 radians.  The return value is in the range @code{-1} to @code{1}.
157 @end deftypefun
158
159 @comment math.h
160 @comment ANSI
161 @deftypefun double tan (double @var{x})
162 This function returns the tangent of @var{x}, where @var{x} is given in
163 radians.
164
165 The following @code{errno} error conditions are defined for this function:
166
167 @table @code
168 @item ERANGE
169 Mathematically, the tangent function has singularities at odd multiples of
170 pi/2.  If the argument @var{x} is too close to one of these singularities,
171 @code{tan} sets this error condition and returns either positive or
172 negative @code{HUGE_VAL}.
173 @end table
174 @end deftypefun
175
176
177 @node Inverse Trig Functions
178 @section Inverse Trigonometric Functions
179 @cindex inverse trigonmetric functions
180
181 These are the usual arc sine, arc cosine and arc tangent functions,
182 which are the inverses of the sine, cosine and tangent functions,
183 respectively.
184
185 @comment math.h
186 @comment ANSI
187 @deftypefun double asin (double @var{x})
188 This function computes the arc sine of @var{x}---that is, the value whose
189 sine is @var{x}.  The value is in units of radians.  Mathematically,
190 there are infinitely many such values; the one actually returned is the
191 one between @code{-pi/2} and @code{pi/2} (inclusive).
192
193 The following @code{errno} error conditions are defined for this function:
194
195 @table @code
196 @item EDOM
197 The argument @var{x} is out of range.  The arc sine function is defined
198 mathematically only over the domain @code{-1} to @code{1}.
199 @end table
200 @end deftypefun
201
202 @comment math.h
203 @comment ANSI
204 @deftypefun double acos (double @var{x})
205 This function computes the arc cosine of @var{x}---that is, the value
206 whose cosine is @var{x}.  The value is in units of radians.
207 Mathematically, there are infinitely many such values; the one actually
208 returned is the one between @code{0} and @code{pi} (inclusive).
209
210 The following @code{errno} error conditions are defined for this function:
211
212 @table @code
213 @item EDOM
214 The argument @var{x} is out of range.  The arc cosine function is defined
215 mathematically only over the domain @code{-1} to @code{1}.
216 @end table
217 @end deftypefun
218
219
220 @comment math.h
221 @comment ANSI
222 @deftypefun double atan (double @var{x})
223 This function computes the arc tangent of @var{x}---that is, the value
224 whose tangent is @var{x}.  The value is in units of radians.
225 Mathematically, there are infinitely many such values; the one actually
226 returned is the one between @code{-pi/2} and @code{pi/2}
227 (inclusive).
228 @end deftypefun
229
230 @comment math.h
231 @comment ANSI
232 @deftypefun double atan2 (double @var{y}, double @var{x})
233 This is the two argument arc tangent function.  It is similar to computing
234 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
235 are used to determine the quadrant of the result, and @var{x} is
236 permitted to be zero.  The return value is given in radians and is in
237 the range @code{-pi} to @code{pi}, inclusive.
238
239 If @var{x} and @var{y} are coordinates of a point in the plane,
240 @code{atan2} returns the signed angle between the line from the origin
241 to that point and the x-axis.  Thus, @code{atan2} is useful for
242 converting Cartesian coordinates to polar coordinates.  (To compute the
243 radial coordinate, use @code{hypot}; see @ref{Exponentiation and
244 Logarithms}.)
245
246 The following @code{errno} error conditions are defined for this function:
247
248 @table @code
249 @item EDOM
250 Both the @var{x} and @var{y} arguments are zero; the value of the
251 function is not defined in this case.
252 @end table
253 @end deftypefun
254
255
256 @node Exponents and Logarithms
257 @section Exponentiation and Logarithms
258 @cindex exponentiation functions
259 @cindex power functions
260 @cindex logarithm functions
261
262 @comment math.h
263 @comment ANSI
264 @deftypefun double exp (double @var{x})
265 The @code{exp} function returns the value of e (the base of natural
266 logarithms) raised to power @var{x}.
267
268 The following @code{errno} error conditions are defined for this function:
269
270 @table @code
271 @item ERANGE
272 The magnitude of the result is too large to be representable.
273 @end table
274 @end deftypefun
275
276 @comment math.h
277 @comment ANSI
278 @deftypefun double log (double @var{x})
279 This function returns the natural logarithm of @var{x}.  @code{exp (log
280 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
281 C.
282
283 The following @code{errno} error conditions are defined for this function:
284
285 @table @code
286 @item EDOM
287 The log function is defined mathematically to return a non-complex
288 result only on positive arguments.  This error is used to report a
289 negative argument @var{x}.
290
291 @item ERANGE
292 The result of the function on an argument of zero is not defined.
293 @end table
294 @end deftypefun
295
296 @comment math.h
297 @comment ANSI
298 @deftypefun double log10 (double @var{x})
299 This function returns the base-10 logarithm of @var{x}.  Except for the
300 different base, it is similar to the @code{log} function.  In fact,
301 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
302 @end deftypefun
303
304 @comment math.h
305 @comment ANSI
306 @deftypefun double pow (double @var{base}, double @var{power})
307 This is a general exponentiation function, returning @var{base} raised
308 to @var{power}.
309
310 The following @code{errno} error conditions are defined for this function:
311
312 @table @code
313 @item EDOM
314 The argument @var{base} is negative and @var{power} is not an integral
315 value.  Mathematically, the result would be a complex number in this case.
316
317 @item ERANGE
318 An underflow or overflow condition was detected in the result.
319 @end table
320 @end deftypefun
321
322 @cindex square root function
323 @comment math.h
324 @comment ANSI
325 @deftypefun double sqrt (double @var{x})
326 This function returns the nonnegative square root of @var{x}.
327
328 The following @code{errno} error conditions are defined for this function:
329
330 @table @code
331 @item EDOM
332 The argument @var{x} is negative.  Mathematically, the square root would
333 be a complex number.
334 @end table
335 @end deftypefun
336
337 @cindex cube root function
338 @comment math.h
339 @comment GNU
340 @deftypefun double cbrt (double @var{x})
341 This function returns the cube root of @var{x}.
342 @end deftypefun
343
344 @comment math.h
345 @comment BSD
346 @deftypefun double hypot (double @var{x}, double @var{y})
347 The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
348 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
349 triangle with sides of length @var{x} and @var{y}, or the distance
350 of the point (@var{x}, @var{y}) from the origin.)
351 @end deftypefun
352
353 @comment math.h
354 @comment BSD
355 @deftypefun double cabs (struct @{ double x, y; @} @var{z})
356 The @code{cabs} function is similar to @code{hypot}, but the argument
357 is specified as a @code{struct} representing a complex number.
358 @end deftypefun
359
360
361 @comment math.h
362 @comment BSD
363 @deftypefun double expm1 (double @var{x})
364 This function returns a value equivalent to @code{exp (@var{x}) - 1}.
365 It is computed in a way that is accurate even if the value of @var{x} is
366 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
367 to subtraction of two numbers that are nearly equal.
368 @end deftypefun
369
370 @comment math.h
371 @comment BSD
372 @deftypefun double log1p (double @var{x})
373 This function returns a value equivalent to @code{log (1 + @var{x})}.
374 It is computed in a way that is accurate even if the value of @var{x} is
375 near zero.
376 @end deftypefun
377
378 @node Hyperbolic Functions
379 @section Hyperbolic Functions
380 @cindex hyperbolic functions
381
382 The functions in this section are related to the exponential functions;
383 see @ref{Exponents and Logarithms}.
384
385 @comment math.h
386 @comment ANSI
387 @deftypefun double sinh (double @var{x})
388 The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
389 mathematically as @code{(exp (@var{x}) - exp (-@var{x}) / 2}.
390 The following @code{errno} error conditions are defined for this
391 function:
392
393 @table @code
394 @item ERANGE
395 The value of the argument @var{x} is too large; an overflow condition
396 was detected.
397 @end table
398 @end deftypefun
399
400 @comment math.h
401 @comment ANSI
402 @deftypefun double cosh (double @var{x})
403 The @code{cosh} function returns the hyperbolic cosine of @var{x},
404 defined mathematically as @code{(exp (@var{x}) + exp (-@var{x}) /
405 2}.  The following @code{errno} error conditions are defined for this
406 function:
407
408 @table @code
409 @item ERANGE
410 The value of the argument @var{x} is too large; an overflow condition
411 was detected.
412 @end table
413 @end deftypefun
414
415 @comment math.h
416 @comment ANSI
417 @deftypefun double tanh (double @var{x})
418 This function returns the hyperbolic tangent of @var{x}, defined
419 mathematically as @code{sinh (@var{x}) / cosh (@var{x})}.
420 @end deftypefun
421
422 @cindex inverse hyperbolic functions
423
424 @comment math.h
425 @comment BSD
426 @deftypefun double asinh (double @var{x})
427 This function returns the inverse hyperbolic sine of @var{x}---the
428 value whose hyperbolic sine is @var{x}.
429 @end deftypefun
430
431 @comment math.h
432 @comment BSD
433 @deftypefun double acosh (double @var{x})
434 This function returns the inverse hyperbolic cosine of @var{x}---the
435 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
436 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
437 @end deftypefun
438
439 @comment math.h
440 @comment BSD
441 @deftypefun double atanh (double @var{x})
442 This function returns the inverse hyperbolic tangent of @var{x}---the
443 value whose hyperbolic tangent is @var{x}.  If the absolute value of
444 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
445 @code{HUGE_VAL}.
446 @end deftypefun
447
448 @node Pseudo-Random Numbers
449 @section Pseudo-Random Numbers
450
451 This section describes the GNU facilities for generating a series of
452 pseudo-random numbers.  The numbers generated are not necessarily truly
453 random; typically, the sequences repeat periodically, with the period
454 being a function of the number of bits in the @dfn{seed} or initial
455 state.
456 @cindex random numbers
457 @cindex pseudo-random numbers
458 @cindex seed (for random numbers)
459
460 There are actually two sets of random number functions provided.
461
462 @itemize @bullet
463 @item 
464 The @code{rand} and @code{srand} functions, described in @ref{ANSI C
465 Random Number Functions}, are part of the ANSI C standard.  You can use
466 these functions portably in many C implementations.
467
468 @item 
469 The @code{random} and @code{srandom} functions, described in @ref{BSD
470 Random Number Functions}, are derived from BSD Unix.  This uses a better
471 random number generator (producing numbers that are more random), but
472 is less portable.
473 @end itemize
474
475 For both sets of functions, you can get repeatable sequences of numbers
476 within a single implementation on a single machine type by specifying
477 the same initial seed value for the random number generator.  Other C
478 libraries may produce different sequences of values for the same seed.
479
480
481 @menu
482 * ANSI C Random Number Functions::      @code{rand} and friends.
483 * BSD Random Number Functions::         @code{random} and friends.
484 @end menu
485
486 @node ANSI C Random Number Functions
487 @subsection ANSI C Random Number Functions
488
489 This section describes the random number functions that are part of
490 the ANSI C standard.  These functions represent the state of the
491 random number generator as an @code{int}.
492
493 To use these facilities, you should include the header file
494 @file{stdlib.h} in your program.
495 @pindex stdlib.h
496
497 @comment stdlib.h
498 @comment ANSI
499 @deftypevr Macro int RAND_MAX
500 The value of this macro is an integer constant expression that
501 represents the maximum possible value returned by the @code{rand}
502 function.  In the GNU library, it is @code{037777777}.  In other
503 libraries, it may be as low as @code{32767}.
504 @end deftypevr
505
506 @comment stdlib.h
507 @comment ANSI
508 @deftypefun int rand (void)
509 The @code{rand} function returns the next pseudo-random number in the
510 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
511 @end deftypefun
512
513 @comment stdlib.h
514 @comment ANSI
515 @deftypefun void srand (unsigned int @var{seed})
516 This function establishes @var{seed} as the seed for a new series of
517 pseudo-random numbers.  If you call @code{rand} before a seed has been
518 established with @code{srand}, it uses the value @code{1} as a default
519 seed.
520
521 To produce truly random numbers (not just pseudo-random), do @code{srand
522 (time (0))}.
523 @end deftypefun
524
525 @node BSD Random Number Functions
526 @subsection BSD Random Number Functions
527
528 This section describes a set of random number generation functions
529 that are derived from BSD Unix.  The @code{random} function can generate
530 better random numbers than @code{rand}, because it maintains more bits
531 of internal state.
532
533 The prototypes for these functions are in @file{stdlib.h}.
534 @pindex stdlib.h
535
536 @comment stdlib.h
537 @comment BSD
538 @deftypefun {long int} random (void)
539 This function returns the next pseudo-random number in the sequence.
540 The range of values returned is from @code{0} to @code{RAND_MAX}.
541 @end deftypefun
542
543 @comment stdlib.h
544 @comment BSD
545 @deftypefun void srandom (unsigned int @var{seed})
546 The @code{srandom} function sets the seed for the current random number
547 state based on the integer @var{seed}.  If you supply a @var{seed} value
548 of @code{1}, this will cause @code{random} to reproduce the default set
549 of random numbers.
550
551 To produce truly random numbers (not just pseudo-random), do
552 @code{srandom (time (0))}.
553 @end deftypefun
554
555 Because this random number generator uses more state information than
556 will fit in an @code{int}, @code{srandom} does not return a value that
557 is useful for saving and restoring the random number state.  Instead,
558 you should use the @code{initstate} and @code{setstate} functions to do
559 this.
560
561 @comment stdlib.h
562 @comment BSD
563 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
564 The @code{initstate} function is used to initialize the random number
565 generator state.  The argument @var{state} is an array of @var{size}
566 bytes, used to hold the state information.  The size must be at least 8
567 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
568 the @var{state} array, the better.
569
570 The return value is the previous value of the state information array.
571 You can use this value later as an argument to @code{setstate} to
572 restore that state.
573 @end deftypefun
574
575 @comment stdlib.h
576 @comment BSD
577 @deftypefun {void *} setstate (void *@var{state})
578 The @code{setstate} function restores the random number state
579 information @var{state}.  The argument must have been the result of
580 a previous call to @var{initstate} or @var{setstate}.  
581
582 The return value is the previous value of the state information array.
583 You can use thise value later as an argument to @code{setstate} to
584 restore that state.
585 @end deftypefun
586
587 @node Absolute Value
588 @section Absolute Value
589 @cindex absolute value functions
590
591 These functions are provided for obtaining the @dfn{absolute value} (or
592 @dfn{magnitude}) of a number.  The absolute value of @var{x} is @var{x}
593 is @var{x} is positive, @minus{}@var{x} if @var{x} is negative.
594
595 Prototypes for @code{abs} and @code{abs} are declared in
596 @file{stdlib.h}; @code{fabs} is declared in @file{math.h}.
597 @pindex math.h
598 @pindex stdlib.h
599
600 @comment stdlib.h
601 @comment ANSI
602 @deftypefun int abs (int @var{number})
603 This function returns the absolute value of @var{number}.
604
605 Most computers use a two's complement integer representation, in which
606 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
607 cannot be represented; thus, @code{abs (INT_MIN)} is not defined.
608 @end deftypefun
609
610 @comment stdlib.h
611 @comment ANSI
612 @deftypefun {long int} labs (long int @var{number})
613 This is similar to @code{abs}, except that both the argument and result
614 are of type @code{long int} rather than @code{int}.
615 @end deftypefun
616
617 @comment math.h
618 @comment ANSI
619 @deftypefun double fabs (double @var{number})
620 This function returns the absolute value of the floating-point number
621 @var{number}.
622 @end deftypefun
623
624 There is also the function @code{cabs} for computing the absolute value
625 of a complex number; see @ref{Exponents and Logarithms}.