7de6d169ac971d65a58ecd671f062da8ad63d6f5
[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 the future,
12 there may be additional functions that operate on @code{float} and
13 @code{long double} values.  For example, @code{cosf} and @code{cosl}
14 would be versions of the @code{cos} function that operate on
15 @code{float} and @code{long double} arguments, respectively.  In the
16 meantime, you should avoid using these names yourself.  @xref{Reserved
17 Names}.
18
19 @menu
20 * Domain and Range Errors::     Detecting overflow conditions and the like.
21 * Trig Functions::              Sine, cosine, and tangent.
22 * Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
23 * Exponents and Logarithms::    Also includes square root.
24 * Hyperbolic Functions::        Hyperbolic sine and friends.
25 * Pseudo-Random Numbers::       Functions for generating pseudo-random
26                                  numbers.
27 @end menu
28
29 @node Domain and Range Errors
30 @section Domain and Range Errors
31
32 @cindex domain error
33 Many of the functions listed in this chapter are defined mathematically
34 over a domain that is only a subset of real numbers.  For example, the
35 @code{acos} function is defined over the domain between @code{-1} and
36 @code{1}.  If you pass an argument to one of these functions that is
37 outside the domain over which it is defined, the function sets
38 @code{errno} to @code{EDOM} to indicate a @dfn{domain error}.  On
39 machines that support @w{IEEE 754} floating point, functions reporting
40 error @code{EDOM} also return a NaN.
41
42 Some of these functions are defined mathematically to result in a
43 complex value over parts of their domains.  The most familiar example of
44 this is taking the square root of a negative number.  The functions in
45 this chapter take only real arguments and return only real values;
46 therefore, if the value ought to be nonreal, this is treated as a domain
47 error.
48
49 @cindex range error
50 A related problem is that the mathematical result of a function may not
51 be representable as a floating point number.  If magnitude of the
52 correct result is too large to be represented, the function sets
53 @code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
54 returns a particular very large value (named by the macro
55 @code{HUGE_VAL}) or its negation (@w{@code{- HUGE_VAL}}).
56
57 If the magnitude of the result is too small, a value of zero is returned
58 instead.  In this case, @code{errno} might or might not be
59 set to @code{ERANGE}.
60
61 The only completely reliable way to check for domain and range errors is
62 to set @code{errno} to @code{0} before you call the mathematical function
63 and test @code{errno} afterward.  As a consequence of this use of
64 @code{errno}, use of the mathematical functions is not reentrant if you
65 check for errors.
66
67 @c !!! this isn't always true at the moment....
68 None of the mathematical functions ever generates signals as a result of
69 domain or range errors.  In particular, this means that you won't see
70 @code{SIGFPE} signals generated within these functions.  (@xref{Signal
71 Handling}, for more information about signals.)
72
73 @comment math.h
74 @comment ANSI
75 @deftypevr Macro double HUGE_VAL
76 An expression representing a particular very large number.  On machines
77 that use @w{IEEE 754} floating point format, the value is ``infinity''.
78 On other machines, it's typically the largest positive number that can
79 be represented.
80
81 The value of this macro is used as the return value from various
82 mathematical @code{double} returning functions in overflow situations.
83 @end deftypevr
84
85 @comment math.h
86 @comment GNU
87 @deftypevr Macro float HUGE_VALf
88 This macro is similar to the @code{HUGE_VAL} macro except that it is
89 used by functions returning @code{float} values.
90
91 This macro is a GNU extension.
92 @end deftypevr
93
94 @comment math.h
95 @comment GNU
96 @deftypevr Macro {long double} HUGE_VALl
97 This macro is similar to the @code{HUGE_VAL} macro except that it is
98 used by functions returning @code{long double} values.  The value is
99 only different from @code{HUGE_VAL} if the architecture really supports
100 @code{long double} values.
101
102 This macro is a GNU extension.
103 @end deftypevr
104
105
106 @comment
107
108 For more information about floating-point representations and limits,
109 see @ref{Floating Point Parameters}.  In particular, the macro
110 @code{DBL_MAX} might be more appropriate than @code{HUGE_VAL} for many
111 uses other than testing for an error in a mathematical function.
112
113 @node Trig Functions
114 @section Trigonometric Functions
115 @cindex trigonometric functions
116
117 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
118 The arguments to all of these functions are in units of radians; recall
119 that pi radians equals 180 degrees.
120
121 @cindex pi (trigonometric constant)
122 The math library doesn't define a symbolic constant for pi, but you can
123 define your own if you need one:
124
125 @smallexample
126 #define PI 3.14159265358979323846264338327
127 @end smallexample
128
129 @noindent
130 You can also compute the value of pi with the expression @code{acos
131 (-1.0)}.
132
133
134 @comment math.h
135 @comment ANSI
136 @deftypefun double sin (double @var{x})
137 This function returns the sine of @var{x}, where @var{x} is given in
138 radians.  The return value is in the range @code{-1} to @code{1}.
139 @end deftypefun
140
141 @comment math.h
142 @comment ANSI
143 @deftypefun double cos (double @var{x})
144 This function returns the cosine 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 tan (double @var{x})
151 This function returns the tangent of @var{x}, where @var{x} is given in
152 radians.
153
154 The following @code{errno} error conditions are defined for this function:
155
156 @table @code
157 @item ERANGE
158 Mathematically, the tangent function has singularities at odd multiples
159 of pi/2.  If the argument @var{x} is too close to one of these
160 singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
161 either positive or negative @code{HUGE_VAL}.
162 @end table
163 @end deftypefun
164
165
166 @node Inverse Trig Functions
167 @section Inverse Trigonometric Functions
168 @cindex inverse trigonmetric functions
169
170 These are the usual arc sine, arc cosine and arc tangent functions,
171 which are the inverses of the sine, cosine and tangent functions,
172 respectively.
173
174 @comment math.h
175 @comment ANSI
176 @deftypefun double asin (double @var{x})
177 This function computes the arc sine of @var{x}---that is, the value whose
178 sine is @var{x}.  The value is in units of radians.  Mathematically,
179 there are infinitely many such values; the one actually returned is the
180 one between @code{-pi/2} and @code{pi/2} (inclusive).
181
182 @code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
183 out of range.  The arc sine function is defined mathematically only
184 over the domain @code{-1} to @code{1}.
185 @end deftypefun
186
187 @comment math.h
188 @comment ANSI
189 @deftypefun double acos (double @var{x})
190 This function computes the arc cosine of @var{x}---that is, the value
191 whose cosine is @var{x}.  The value is in units of radians.
192 Mathematically, there are infinitely many such values; the one actually
193 returned is the one between @code{0} and @code{pi} (inclusive).
194
195 @code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
196 out of range.  The arc cosine function is defined mathematically only
197 over the domain @code{-1} to @code{1}.
198 @end deftypefun
199
200
201 @comment math.h
202 @comment ANSI
203 @deftypefun double atan (double @var{x})
204 This function computes the arc tangent of @var{x}---that is, the value
205 whose tangent is @var{x}.  The value is in units of radians.
206 Mathematically, there are infinitely many such values; the one actually
207 returned is the one between @code{-pi/2} and @code{pi/2}
208 (inclusive).
209 @end deftypefun
210
211 @comment math.h
212 @comment ANSI
213 @deftypefun double atan2 (double @var{y}, double @var{x})
214 This is the two argument arc tangent function.  It is similar to computing
215 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
216 are used to determine the quadrant of the result, and @var{x} is
217 permitted to be zero.  The return value is given in radians and is in
218 the range @code{-pi} to @code{pi}, inclusive.
219
220 If @var{x} and @var{y} are coordinates of a point in the plane,
221 @code{atan2} returns the signed angle between the line from the origin
222 to that point and the x-axis.  Thus, @code{atan2} is useful for
223 converting Cartesian coordinates to polar coordinates.  (To compute the
224 radial coordinate, use @code{hypot}; see @ref{Exponents and
225 Logarithms}.)
226
227 The function @code{atan2} sets @code{errno} to @code{EDOM} if both
228 @var{x} and @var{y} are zero; the return value is not defined in this
229 case.
230 @end deftypefun
231
232
233 @node Exponents and Logarithms
234 @section Exponentiation and Logarithms
235 @cindex exponentiation functions
236 @cindex power functions
237 @cindex logarithm functions
238
239 @comment math.h
240 @comment ANSI
241 @deftypefun double exp (double @var{x})
242 The @code{exp} function returns the value of e (the base of natural
243 logarithms) raised to power @var{x}.
244
245 The function fails, and sets @code{errno} to @code{ERANGE}, if the
246 magnitude of the result is too large to be representable.
247 @end deftypefun
248
249 @comment math.h
250 @comment ANSI
251 @deftypefun double log (double @var{x})
252 This function returns the natural logarithm of @var{x}.  @code{exp (log
253 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
254 C.
255
256 The following @code{errno} error conditions are defined for this function:
257
258 @table @code
259 @item EDOM
260 The argument @var{x} is negative.  The log function is defined
261 mathematically to return a real result only on positive arguments.
262
263 @item ERANGE
264 The argument is zero.  The log of zero is not defined.
265 @end table
266 @end deftypefun
267
268 @comment math.h
269 @comment ANSI
270 @deftypefun double log10 (double @var{x})
271 This function returns the base-10 logarithm of @var{x}.  Except for the
272 different base, it is similar to the @code{log} function.  In fact,
273 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
274 @end deftypefun
275
276 @comment math.h
277 @comment ANSI
278 @deftypefun double pow (double @var{base}, double @var{power})
279 This is a general exponentiation function, returning @var{base} raised
280 to @var{power}.
281
282 @need 250
283 The following @code{errno} error conditions are defined for this function:
284
285 @table @code
286 @item EDOM
287 The argument @var{base} is negative and @var{power} is not an integral
288 value.  Mathematically, the result would be a complex number in this case.
289
290 @item ERANGE
291 An underflow or overflow condition was detected in the result.
292 @end table
293 @end deftypefun
294
295 @cindex square root function
296 @comment math.h
297 @comment ANSI
298 @deftypefun double sqrt (double @var{x})
299 This function returns the nonnegative square root of @var{x}.
300
301 The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
302 @var{x} is negative.  Mathematically, the square root would be a complex
303 number.
304 @end deftypefun
305
306 @cindex cube root function
307 @comment math.h
308 @comment BSD
309 @deftypefun double cbrt (double @var{x})
310 This function returns the cube root of @var{x}.  This function cannot
311 fail; every representable real value has a representable real cube root.
312 @end deftypefun
313
314 @comment math.h
315 @comment BSD
316 @deftypefun double hypot (double @var{x}, double @var{y})
317 The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
318 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
319 triangle with sides of length @var{x} and @var{y}, or the distance
320 of the point (@var{x}, @var{y}) from the origin.)  See also the function
321 @code{cabs} in @ref{Absolute Value}.
322 @end deftypefun
323
324 @comment math.h
325 @comment BSD
326 @deftypefun double expm1 (double @var{x})
327 This function returns a value equivalent to @code{exp (@var{x}) - 1}.
328 It is computed in a way that is accurate even if the value of @var{x} is
329 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
330 to subtraction of two numbers that are nearly equal.
331 @end deftypefun
332
333 @comment math.h
334 @comment BSD
335 @deftypefun double log1p (double @var{x})
336 This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
337 It is computed in a way that is accurate even if the value of @var{x} is
338 near zero.
339 @end deftypefun
340
341 @node Hyperbolic Functions
342 @section Hyperbolic Functions
343 @cindex hyperbolic functions
344
345 The functions in this section are related to the exponential functions;
346 see @ref{Exponents and Logarithms}.
347
348 @comment math.h
349 @comment ANSI
350 @deftypefun double sinh (double @var{x})
351 The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
352 mathematically as @w{@code{exp (@var{x}) - exp (-@var{x}) / 2}}.  The
353 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
354 @var{x} is too large; that is, if overflow occurs.
355 @end deftypefun
356
357 @comment math.h
358 @comment ANSI
359 @deftypefun double cosh (double @var{x})
360 The @code{cosh} function returns the hyperbolic cosine of @var{x},
361 defined mathematically as @w{@code{exp (@var{x}) + exp (-@var{x}) / 2}}.
362 The function fails, and sets @code{errno} to @code{ERANGE}, if the value
363 of @var{x} is too large; that is, if overflow occurs.
364 @end deftypefun
365
366 @comment math.h
367 @comment ANSI
368 @deftypefun double tanh (double @var{x})
369 This function returns the hyperbolic tangent of @var{x}, whose
370 mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
371 @end deftypefun
372
373 @cindex inverse hyperbolic functions
374
375 @comment math.h
376 @comment BSD
377 @deftypefun double asinh (double @var{x})
378 This function returns the inverse hyperbolic sine of @var{x}---the
379 value whose hyperbolic sine is @var{x}.
380 @end deftypefun
381
382 @comment math.h
383 @comment BSD
384 @deftypefun double acosh (double @var{x})
385 This function returns the inverse hyperbolic cosine of @var{x}---the
386 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
387 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
388 @end deftypefun
389
390 @comment math.h
391 @comment BSD
392 @deftypefun double atanh (double @var{x})
393 This function returns the inverse hyperbolic tangent of @var{x}---the
394 value whose hyperbolic tangent is @var{x}.  If the absolute value of
395 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
396 @code{HUGE_VAL}.
397 @end deftypefun
398
399 @node Pseudo-Random Numbers
400 @section Pseudo-Random Numbers
401 @cindex random numbers
402 @cindex pseudo-random numbers
403 @cindex seed (for random numbers)
404
405 This section describes the GNU facilities for generating a series of
406 pseudo-random numbers.  The numbers generated are not truly random;
407 typically, they form a sequence that repeats periodically, with a
408 period so large that you can ignore it for ordinary purposes.  The
409 random number generator works by remembering at all times a @dfn{seed}
410 value which it uses to compute the next random number and also to
411 compute a new seed.
412
413 Although the generated numbers look unpredictable within one run of a
414 program, the sequence of numbers is @emph{exactly the same} from one run
415 to the next.  This is because the initial seed is always the same.  This
416 is convenient when you are debugging a program, but it is unhelpful if
417 you want the program to behave unpredictably.  If you want truly random
418 numbers, not just pseudo-random, specify a seed based on the current
419 time.
420
421 You can get repeatable sequences of numbers on a particular machine type
422 by specifying the same initial seed value for the random number
423 generator.  There is no standard meaning for a particular seed value;
424 the same seed, used in different C libraries or on different CPU types,
425 will give you different random numbers.
426
427 The GNU library supports the standard ANSI C random number functions
428 plus another set derived from BSD.  We recommend you use the standard
429 ones, @code{rand} and @code{srand}.
430
431 @menu
432 * ANSI Random::      @code{rand} and friends.
433 * BSD Random::       @code{random} and friends.
434 @end menu
435
436 @node ANSI Random
437 @subsection ANSI C Random Number Functions
438
439 This section describes the random number functions that are part of
440 the ANSI C standard.
441
442 To use these facilities, you should include the header file
443 @file{stdlib.h} in your program.
444 @pindex stdlib.h
445
446 @comment stdlib.h
447 @comment ANSI
448 @deftypevr Macro int RAND_MAX
449 The value of this macro is an integer constant expression that
450 represents the maximum possible value returned by the @code{rand}
451 function.  In the GNU library, it is @code{037777777}, which is the
452 largest signed integer representable in 32 bits.  In other libraries, it
453 may be as low as @code{32767}.
454 @end deftypevr
455
456 @comment stdlib.h
457 @comment ANSI
458 @deftypefun int rand ()
459 The @code{rand} function returns the next pseudo-random number in the
460 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
461 @end deftypefun
462
463 @comment stdlib.h
464 @comment ANSI
465 @deftypefun void srand (unsigned int @var{seed})
466 This function establishes @var{seed} as the seed for a new series of
467 pseudo-random numbers.  If you call @code{rand} before a seed has been
468 established with @code{srand}, it uses the value @code{1} as a default
469 seed.
470
471 To produce truly random numbers (not just pseudo-random), do @code{srand
472 (time (0))}.
473 @end deftypefun
474
475 @node BSD Random
476 @subsection BSD Random Number Functions
477
478 This section describes a set of random number generation functions that
479 are derived from BSD.  There is no advantage to using these functions
480 with the GNU C library; we support them for BSD compatibility only.
481
482 The prototypes for these functions are in @file{stdlib.h}.
483 @pindex stdlib.h
484
485 @comment stdlib.h
486 @comment BSD
487 @deftypefun {long int} random ()
488 This function returns the next pseudo-random number in the sequence.
489 The range of values returned is from @code{0} to @code{RAND_MAX}.
490 @end deftypefun
491
492 @comment stdlib.h
493 @comment BSD
494 @deftypefun void srandom (unsigned int @var{seed})
495 The @code{srandom} function sets the seed for the current random number
496 state based on the integer @var{seed}.  If you supply a @var{seed} value
497 of @code{1}, this will cause @code{random} to reproduce the default set
498 of random numbers.
499
500 To produce truly random numbers (not just pseudo-random), do
501 @code{srandom (time (0))}.
502 @end deftypefun
503
504 @comment stdlib.h
505 @comment BSD
506 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
507 The @code{initstate} function is used to initialize the random number
508 generator state.  The argument @var{state} is an array of @var{size}
509 bytes, used to hold the state information.  The size must be at least 8
510 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
511 the @var{state} array, the better.
512
513 The return value is the previous value of the state information array.
514 You can use this value later as an argument to @code{setstate} to
515 restore that state.
516 @end deftypefun
517
518 @comment stdlib.h
519 @comment BSD
520 @deftypefun {void *} setstate (void *@var{state})
521 The @code{setstate} function restores the random number state
522 information @var{state}.  The argument must have been the result of
523 a previous call to @var{initstate} or @var{setstate}.
524
525 The return value is the previous value of the state information array.
526 You can use thise value later as an argument to @code{setstate} to
527 restore that state.
528 @end deftypefun