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