Removing assert.texinfo, an adjacent file.
[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 * Trigonometric Functions::     Sine, cosine, and tangent.
26 * Inverse Trigonometric Functions::  Arc sine, arc cosine, and arc tangent.
27 * Exponentiation 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, Not a Number,  , Mathematics
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, Trigonometric Functions, Domain and Range Errors, Mathematics
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 @end deftypevr
119
120 @node Trigonometric Functions, Inverse Trigonometric Functions, Not a Number, Mathematics
121 @section Trigonometric Functions
122 @cindex trigonometric functions
123
124 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
125 The arguments to all of these functions are in units of radians; recall
126 that pi radians equals 180 degrees.
127
128 @cindex pi (trigonometric constant)
129 The math library doesn't define a symbolic constant for pi, but you can
130 define your own if you need one:
131
132 @example
133 #define PI 3.14159265358979323846264338327
134 @end example
135
136 @noindent
137 You can also compute the value of pi with the expression @code{acos
138 (-1.0)}.
139
140
141 @comment math.h
142 @comment ANSI
143 @deftypefun double sin (double @var{x})
144 This function returns the sine of @var{x}, where @var{x} is given in
145 radians.  The return value is in the range @code{-1} to @code{1}.
146 @end deftypefun
147
148 @comment math.h
149 @comment ANSI
150 @deftypefun double cos (double @var{x})
151 This function returns the cosine of @var{x}, where @var{x} is given in
152 radians.  The return value is in the range @code{-1} to @code{1}.
153 @end deftypefun
154
155 @comment math.h
156 @comment ANSI
157 @deftypefun double tan (double @var{x})
158 This function returns the tangent of @var{x}, where @var{x} is given in
159 radians.
160
161 The following @code{errno} error conditions are defined for this function:
162
163 @table @code
164 @item ERANGE
165 Mathematically, the tangent function has singularities at odd multiples of
166 pi/2.  If the argument @var{x} is too close to one of these singularities,
167 @code{tan} sets this error condition and returns either positive or
168 negative @code{HUGE_VAL}.
169 @end table
170 @end deftypefun
171
172
173 @node Inverse Trigonometric Functions, Exponentiation and Logarithms, Trigonometric Functions, Mathematics
174 @section Inverse Trigonometric Functions
175 @cindex inverse trigonmetric functions
176
177 These are the usual arc sine, arc cosine and arc tangent functions,
178 which are the inverses of the sine, cosine and tangent functions,
179 respectively.
180
181 @comment math.h
182 @comment ANSI
183 @deftypefun double asin (double @var{x})
184 This function computes the arc sine of @var{x}---that is, the value whose
185 sine is @var{x}.  The value is in units of radians.  Mathematically,
186 there are infinitely many such values; the one actually returned is the
187 one between @code{-pi/2} and @code{pi/2} (inclusive).
188
189 The following @code{errno} error conditions are defined for this function:
190
191 @table @code
192 @item EDOM
193 The argument @var{x} is out of range.  The arc sine function is defined
194 mathematically only over the domain @code{-1} to @code{1}.
195 @end table
196 @end deftypefun
197
198 @comment math.h
199 @comment ANSI
200 @deftypefun double acos (double @var{x})
201 This function computes the arc cosine of @var{x}---that is, the value
202 whose cosine is @var{x}.  The value is in units of radians.
203 Mathematically, there are infinitely many such values; the one actually
204 returned is the one between @code{0} and @code{pi} (inclusive).
205
206 The following @code{errno} error conditions are defined for this function:
207
208 @table @code
209 @item EDOM
210 The argument @var{x} is out of range.  The arc cosine function is defined
211 mathematically only over the domain @code{-1} to @code{1}.
212 @end table
213 @end deftypefun
214
215
216 @comment math.h
217 @comment ANSI
218 @deftypefun double atan (double @var{x})
219 This function computes the arc tangent of @var{x}---that is, the value
220 whose tangent is @var{x}.  The value is in units of radians.
221 Mathematically, there are infinitely many such values; the one actually
222 returned is the one between @code{-pi/2} and @code{pi/2}
223 (inclusive).
224 @end deftypefun
225
226 @comment math.h
227 @comment ANSI
228 @deftypefun double atan2 (double @var{y}, double @var{x})
229 This is the two argument arc tangent function.  It is similar to computing
230 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
231 are used to determine the quadrant of the result, and @var{x} is
232 permitted to be zero.  The return value is given in radians and is in
233 the range @code{-pi} to @code{pi}, inclusive.
234
235 If @var{x} and @var{y} are coordinates of a point in the plane,
236 @code{atan2} returns the signed angle between the line from the origin
237 to that point and the x-axis.  Thus, @code{atan2} is useful for
238 converting Cartesian coordinates to polar coordinates.  (To compute the
239 radial coordinate, use @code{hypot}; see @ref{Exponentiation and
240 Logarithms}.)
241
242 The following @code{errno} error conditions are defined for this function:
243
244 @table @code
245 @item EDOM
246 Both the @var{x} and @var{y} arguments are zero; the value of the
247 function is not defined in this case.
248 @end table
249 @end deftypefun
250
251
252 @node Exponentiation and Logarithms, Hyperbolic Functions, Inverse Trigonometric Functions, Mathematics
253 @section Exponentiation and Logarithms
254 @cindex exponentiation functions
255 @cindex power functions
256 @cindex logarithm functions
257
258 @comment math.h
259 @comment ANSI
260 @deftypefun double exp (double @var{x})
261 The @code{exp} function returns the value of e (the base of natural
262 logarithms) raised to power @var{x}.
263
264 The following @code{errno} error conditions are defined for this function:
265
266 @table @code
267 @item ERANGE
268 The magnitude of the result is too large to be representable.
269 @end table
270 @end deftypefun
271
272 @comment math.h
273 @comment ANSI
274 @deftypefun double log (double @var{x})
275 This function returns the natural logarithm of @var{x}.  @code{exp (log
276 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
277 C.
278
279 The following @code{errno} error conditions are defined for this function:
280
281 @table @code
282 @item EDOM
283 The log function is defined mathematically to return a non-complex
284 result only on positive arguments.  This error is used to report a
285 negative argument @var{x}.
286
287 @item ERANGE
288 The result of the function on an argument of zero is not defined.
289 @end table
290 @end deftypefun
291
292 @comment math.h
293 @comment ANSI
294 @deftypefun double log10 (double @var{x})
295 This function returns the base-10 logarithm of @var{x}.  Except for the
296 different base, it is similar to the @code{log} function.  In fact,
297 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
298 @end deftypefun
299
300 @comment math.h
301 @comment ANSI
302 @deftypefun double pow (double @var{base}, double @var{power})
303 This is a general exponentiation function, returning @var{base} raised
304 to @var{power}.
305
306 The following @code{errno} error conditions are defined for this function:
307
308 @table @code
309 @item EDOM
310 The argument @var{base} is negative and @var{power} is not an integral
311 value.  Mathematically, the result would be a complex number in this case.
312
313 @item ERANGE
314 An underflow or overflow condition was detected in the result.
315 @end table
316 @end deftypefun
317
318 @cindex square root function
319 @comment math.h
320 @comment ANSI
321 @deftypefun double sqrt (double @var{x})
322 This function returns the nonnegative square root of @var{x}.
323
324 The following @code{errno} error conditions are defined for this function:
325
326 @table @code
327 @item EDOM
328 The argument @var{x} is negative.  Mathematically, the square root would
329 be a complex number.
330 @end table
331 @end deftypefun
332
333 @cindex cube root function
334 @comment math.h
335 @comment GNU
336 @deftypefun double cbrt (double @var{x})
337 This function returns the cube root of @var{x}.
338 @end deftypefun
339
340 @comment math.h
341 @comment GNU
342 @deftypefun double hypot (double @var{x}, double @var{y})
343 The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
344 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
345 triangle with sides of length @var{x} and @var{y}, or the distance
346 of the point (@var{x}, @var{y}) from the origin.)
347 @end deftypefun
348
349 @comment math.h
350 @comment GNU
351 @deftypefun double cabs (struct @{ double x, y; @} @var{z})
352 The @code{cabs} function is similar to @code{hypot}, but the argument
353 is specified as a @code{struct} representing a complex number.
354 @end deftypefun
355
356
357 @comment math.h
358 @comment GNU
359 @deftypefun double expm1 (double @var{x})
360 This function returns a value equivalent to @code{exp (@var{x}) - 1}.
361 It is computed in a way that is accurate even if the value of @var{x} is
362 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
363 to subtraction of two numbers that are nearly equal.
364 @end deftypefun
365
366 @comment math.h
367 @comment GNU
368 @deftypefun double log1p (double @var{x})
369 This function returns a value equivalent to @code{log (1 + @var{x})}.
370 It is computed in a way that is accurate even if the value of @var{x} is
371 near zero.
372 @end deftypefun
373
374 @node Hyperbolic Functions, Pseudo-Random Numbers, Exponentiation and Logarithms, Mathematics
375 @section Hyperbolic Functions
376 @cindex hyperbolic functions
377
378 The functions in this section are related to the exponential functions;
379 see @ref{Exponentiation and Logarithms}.
380
381 @comment math.h
382 @comment ANSI
383 @deftypefun double sinh (double @var{x})
384 The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
385 mathematically as @code{(exp (@var{x}) - exp (-@var{x}) / 2}.
386 The following @code{errno} error conditions are defined for this
387 function:
388
389 @table @code
390 @item ERANGE
391 The value of the argument @var{x} is too large; an overflow condition
392 was detected.
393 @end table
394 @end deftypefun
395
396 @comment math.h
397 @comment ANSI
398 @deftypefun double cosh (double @var{x})
399 The @code{cosh} function returns the hyperbolic cosine of @var{x},
400 defined mathematically as @code{(exp (@var{x}) + exp (-@var{x}) /
401 2}.  The following @code{errno} error conditions are defined for this
402 function:
403
404 @table @code
405 @item ERANGE
406 The value of the argument @var{x} is too large; an overflow condition
407 was detected.
408 @end table
409 @end deftypefun
410
411 @comment math.h
412 @comment ANSI
413 @deftypefun double tanh (double @var{x})
414 This function returns the hyperbolic tangent of @var{x}, defined
415 mathematically as @code{sinh (@var{x}) / cosh (@var{x})}.
416 @end deftypefun
417
418 @cindex inverse hyperbolic functions
419
420 @comment math.h
421 @comment GNU
422 @deftypefun double asinh (double @var{x})
423 This function returns the inverse hyperbolic sine of @var{x}---the
424 value whose hyperbolic sine is @var{x}.
425 @end deftypefun
426
427 @comment math.h
428 @comment GNU
429 @deftypefun double acosh (double @var{x})
430 This function returns the inverse hyperbolic cosine of @var{x}---the
431 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
432 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
433 @end deftypefun
434
435 @comment math.h
436 @comment GNU
437 @deftypefun double atanh (double @var{x})
438 This function returns the inverse hyperbolic tangent of @var{x}---the
439 value whose hyperbolic tangent is @var{x}.  If the absolute value of
440 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
441 @code{HUGE_VAL}.
442 @end deftypefun
443
444 @node Pseudo-Random Numbers, Absolute Value, Hyperbolic Functions, Mathematics
445 @section Pseudo-Random Numbers
446
447 This section describes the GNU facilities for generating a series of
448 pseudo-random numbers.  The numbers generated are not necessarily truly
449 random; typically, the sequences repeat periodically, with the period
450 being a function of the number of bits in the @dfn{seed} or initial
451 state.
452 @cindex random numbers
453 @cindex pseudo-random numbers
454 @cindex seed (for random numbers)
455
456 There are actually two sets of random number functions provided.
457
458 @itemize @bullet
459 @item 
460 The @code{rand} and @code{srand} functions, described in @ref{ANSI C
461 Random Number Functions}, are part of the ANSI C standard.  You can use
462 these functions portably in many C implementations.
463
464 @item 
465 The @code{random} and @code{srandom} functions, described in @ref{BSD
466 Random Number Functions}, are derived from BSD Unix.  This uses a better
467 random number generator (producing numbers that are more random), but
468 is less portable.
469 @end itemize
470
471 For both sets of functions, you can get repeatable sequences of numbers
472 within a single implementation on a single machine type by specifying
473 the same initial seed value for the random number generator.  Other C
474 libraries may produce different sequences of values for the same seed.
475
476
477 @menu
478 * ANSI C Random Number Functions::  @code{rand} and friends.
479 * BSD Random Number Functions::  @code{random} and friends.
480 @end menu
481
482 @node ANSI C Random Number Functions, BSD Random Number Functions,  , Pseudo-Random Numbers
483 @subsection ANSI C Random Number Functions
484
485 This section describes the random number functions that are part of
486 the ANSI C standard.  These functions represent the state of the
487 random number generator as an @code{int}.
488
489 To use these facilities, you should include the header file
490 @file{stdlib.h} in your program.
491 @pindex stdlib.h
492
493 @comment stdlib.h
494 @comment ANSI
495 @deftypevr Macro int RAND_MAX
496 The value of this macro is an integer constant expression that
497 represents the maximum possible value returned by the @code{rand}
498 function.  In the GNU library, it is @code{037777777}.  In other
499 libraries, it may be as low as @code{32767}.
500 @end deftypevr
501
502 @comment stdlib.h
503 @comment ANSI
504 @deftypefun int rand (void)
505 The @code{rand} function returns the next pseudo-random number in the
506 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
507 @end deftypefun
508
509 @comment stdlib.h
510 @comment ANSI
511 @deftypefun void srand (unsigned int @var{seed})
512 This function establishes @var{seed} as the seed for a new series of
513 pseudo-random numbers.  If you call @code{rand} before a seed has been
514 established with @code{srand}, it uses the value @code{1} as a default
515 seed.
516
517 To produce truly random numbers (not just pseudo-random), do @code{srand
518 (time (0))}.
519 @end deftypefun
520
521 @node BSD Random Number Functions,  , ANSI C Random Number Functions, Pseudo-Random Numbers
522 @subsection BSD Random Number Functions
523
524 This section describes a set of random number generation functions
525 that are derived from BSD Unix.  The @code{random} function can generate
526 better random numbers than @code{rand}, because it maintains more bits
527 of internal state.
528
529 The prototypes for these functions are in @file{stdlib.h}.
530 @pindex stdlib.h
531
532 @comment stdlib.h
533 @comment BSD
534 @deftypefun {long int} random (void)
535 This function returns the next pseudo-random number in the sequence.
536 The range of values returned is from @code{0} to @code{RAND_MAX}.
537 @end deftypefun
538
539 @comment stdlib.h
540 @comment BSD
541 @deftypefun void srandom (unsigned int @var{seed})
542 The @code{srandom} function sets the seed for the current random number
543 state based on the integer @var{seed}.  If you supply a @var{seed} value
544 of @code{1}, this will cause @code{random} to reproduce the default set
545 of random numbers.
546
547 To produce truly random numbers (not just pseudo-random), do
548 @code{srandom (time (0))}.
549 @end deftypefun
550
551 Because this random number generator uses more state information than
552 will fit in an @code{int}, @code{srandom} does not return a value that
553 is useful for saving and restoring the random number state.  Instead,
554 you should use the @code{initstate} and @code{setstate} functions to do
555 this.
556
557 @comment stdlib.h
558 @comment BSD
559 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
560 The @code{initstate} function is used to initialize the random number
561 generator state.  The argument @var{state} is an array of @var{size}
562 bytes, used to hold the state information.  The size must be at least 8
563 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
564 the @var{state} array, the better.
565
566 The return value is the previous value of the state information array.
567 You can use this value later as an argument to @code{setstate} to
568 restore that state.
569 @end deftypefun
570
571 @comment stdlib.h
572 @comment BSD
573 @deftypefun {void *} setstate (void *@var{state})
574 The @code{setstate} function restores the random number state
575 information @var{state}.  The argument must have been the result of
576 a previous call to @var{initstate} or @var{setstate}.  
577
578 The return value is the previous value of the state information array.
579 You can use thise value later as an argument to @code{setstate} to
580 restore that state.
581 @end deftypefun
582
583 @node Absolute Value,  , Pseudo-Random Numbers, Mathematics
584 @section Absolute Value
585 @cindex absolute value functions
586
587 These functions are provided for obtaining the @dfn{absolute value} (or
588 @dfn{magnitude}) of a number.  The absolute value of @var{x} is @var{x}
589 is @var{x} is positive, @minus{}@var{x} if @var{x} is negative.
590
591 Prototypes for @code{abs} and @code{abs} are declared in
592 @file{stdlib.h}; @code{fabs} is declared in @file{math.h}.
593 @pindex math.h
594 @pindex stdlib.h
595
596 @comment stdlib.h
597 @comment ANSI
598 @deftypefun int abs (int @var{number})
599 This function returns the absolute value of @var{number}.
600
601 Most computers use a two's complement integer representation, in which
602 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
603 cannot be represented; thus, @code{abs (INT_MIN)} is not defined.
604 @end deftypefun
605
606 @comment stdlib.h
607 @comment ANSI
608 @deftypefun {long int} labs (long int @var{number})
609 This is similar to @code{abs}, except that both the argument and result
610 are of type @code{long int} rather than @code{int}.
611 @end deftypefun
612
613 @comment math.h
614 @comment ANSI
615 @deftypefun double fabs (double @var{number})
616 This function returns the absolute value of the floating-point number
617 @var{number}.
618 @end deftypefun
619
620 There is also the function @code{cabs} for computing the absolute value
621 of a complex number; see @ref{Exponentiation and Logarithms}.