Miscellaneous corrections after 1st proofreading.
[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 returns
38 an unspecified value and sets @code{errno} to @code{EDOM} to indicate
39 a @dfn{domain error}.
40 @c !!! the "unspecified value" is NAN on ieee754 machines
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 IEEE floating point format, the value is ``infinity''.  On
78 other machines, it's typically the largest positive number that can be
79 represented.
80
81 The value of this macro is used as the return value from various 
82 mathematical functions in overflow situations.
83 @end deftypevr
84
85 For more information about floating-point representations and limits,
86 see @ref{Floating Point Parameters}.  In particular, the macro
87 @code{DBL_MAX} might be more appropriate than @code{HUGE_VAL} for many
88 uses other than testing for an error in a mathematical function.
89
90 @node Trig Functions
91 @section Trigonometric Functions
92 @cindex trigonometric functions
93
94 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
95 The arguments to all of these functions are in units of radians; recall
96 that pi radians equals 180 degrees.
97
98 @cindex pi (trigonometric constant)
99 The math library doesn't define a symbolic constant for pi, but you can
100 define your own if you need one:
101
102 @example
103 #define PI 3.14159265358979323846264338327
104 @end example
105
106 @noindent
107 You can also compute the value of pi with the expression @code{acos
108 (-1.0)}.
109
110
111 @comment math.h
112 @comment ANSI
113 @deftypefun double sin (double @var{x})
114 This function returns the sine of @var{x}, where @var{x} is given in
115 radians.  The return value is in the range @code{-1} to @code{1}.
116 @end deftypefun
117
118 @comment math.h
119 @comment ANSI
120 @deftypefun double cos (double @var{x})
121 This function returns the cosine of @var{x}, where @var{x} is given in
122 radians.  The return value is in the range @code{-1} to @code{1}.
123 @end deftypefun
124
125 @comment math.h
126 @comment ANSI
127 @deftypefun double tan (double @var{x})
128 This function returns the tangent of @var{x}, where @var{x} is given in
129 radians.
130
131 The following @code{errno} error conditions are defined for this function:
132
133 @table @code
134 @item ERANGE
135 Mathematically, the tangent function has singularities at odd multiples
136 of pi/2.  If the argument @var{x} is too close to one of these
137 singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
138 either positive or negative @code{HUGE_VAL}.
139 @end table
140 @end deftypefun
141
142
143 @node Inverse Trig Functions
144 @section Inverse Trigonometric Functions
145 @cindex inverse trigonmetric functions
146
147 These are the usual arc sine, arc cosine and arc tangent functions,
148 which are the inverses of the sine, cosine and tangent functions,
149 respectively.
150
151 @comment math.h
152 @comment ANSI
153 @deftypefun double asin (double @var{x})
154 This function computes the arc sine of @var{x}---that is, the value whose
155 sine is @var{x}.  The value is in units of radians.  Mathematically,
156 there are infinitely many such values; the one actually returned is the
157 one between @code{-pi/2} and @code{pi/2} (inclusive).
158
159 @code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
160 out of range.  The arc sine function is defined mathematically only
161 over the domain @code{-1} to @code{1}.
162 @end deftypefun
163
164 @comment math.h
165 @comment ANSI
166 @deftypefun double acos (double @var{x})
167 This function computes the arc cosine of @var{x}---that is, the value
168 whose cosine is @var{x}.  The value is in units of radians.
169 Mathematically, there are infinitely many such values; the one actually
170 returned is the one between @code{0} and @code{pi} (inclusive).
171
172 @code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
173 out of range.  The arc cosine function is defined mathematically only
174 over the domain @code{-1} to @code{1}.
175 @end deftypefun
176
177
178 @comment math.h
179 @comment ANSI
180 @deftypefun double atan (double @var{x})
181 This function computes the arc tangent of @var{x}---that is, the value
182 whose tangent is @var{x}.  The value is in units of radians.
183 Mathematically, there are infinitely many such values; the one actually
184 returned is the one between @code{-pi/2} and @code{pi/2}
185 (inclusive).
186 @end deftypefun
187
188 @comment math.h
189 @comment ANSI
190 @deftypefun double atan2 (double @var{y}, double @var{x})
191 This is the two argument arc tangent function.  It is similar to computing
192 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
193 are used to determine the quadrant of the result, and @var{x} is
194 permitted to be zero.  The return value is given in radians and is in
195 the range @code{-pi} to @code{pi}, inclusive.
196
197 If @var{x} and @var{y} are coordinates of a point in the plane,
198 @code{atan2} returns the signed angle between the line from the origin
199 to that point and the x-axis.  Thus, @code{atan2} is useful for
200 converting Cartesian coordinates to polar coordinates.  (To compute the
201 radial coordinate, use @code{hypot}; see @ref{Exponents and
202 Logarithms}.)
203
204 The function @code{atan2} sets @code{errno} to @code{EDOM} if both
205 @var{x} and @var{y} are zero; the return value is not defined in this
206 case.
207 @end deftypefun
208
209
210 @node Exponents and Logarithms
211 @section Exponentiation and Logarithms
212 @cindex exponentiation functions
213 @cindex power functions
214 @cindex logarithm functions
215
216 @comment math.h
217 @comment ANSI
218 @deftypefun double exp (double @var{x})
219 The @code{exp} function returns the value of e (the base of natural
220 logarithms) raised to power @var{x}.
221
222 The function fails, and sets @code{errno} to @code{ERANGE}, if the
223 magnitude of the result is too large to be representable.
224 @end deftypefun
225
226 @comment math.h
227 @comment ANSI
228 @deftypefun double log (double @var{x})
229 This function returns the natural logarithm of @var{x}.  @code{exp (log
230 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
231 C.
232
233 The following @code{errno} error conditions are defined for this function:
234
235 @table @code
236 @item EDOM
237 The argument @var{x} is negative.  The log function is defined
238 mathematically to return a real result only on positive arguments.
239
240 @item ERANGE
241 The argument is zero.  The log of zero is not defined.
242 @end table
243 @end deftypefun
244
245 @comment math.h
246 @comment ANSI
247 @deftypefun double log10 (double @var{x})
248 This function returns the base-10 logarithm of @var{x}.  Except for the
249 different base, it is similar to the @code{log} function.  In fact,
250 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
251 @end deftypefun
252
253 @comment math.h
254 @comment ANSI
255 @deftypefun double pow (double @var{base}, double @var{power})
256 This is a general exponentiation function, returning @var{base} raised
257 to @var{power}.
258
259 @need 250
260 The following @code{errno} error conditions are defined for this function:
261
262 @table @code
263 @item EDOM
264 The argument @var{base} is negative and @var{power} is not an integral
265 value.  Mathematically, the result would be a complex number in this case.
266
267 @item ERANGE
268 An underflow or overflow condition was detected in the result.
269 @end table
270 @end deftypefun
271
272 @cindex square root function
273 @comment math.h
274 @comment ANSI
275 @deftypefun double sqrt (double @var{x})
276 This function returns the nonnegative square root of @var{x}.
277
278 The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
279 @var{x} is negative.  Mathematically, the square root would be a complex
280 number.
281 @end deftypefun
282
283 @cindex cube root function
284 @comment math.h
285 @comment GNU
286 @deftypefun double cbrt (double @var{x})
287 This function returns the cube root of @var{x}.  This function cannot
288 fail; every representable real value has a represetable real cube root.
289 @end deftypefun
290
291 @comment math.h
292 @comment BSD
293 @deftypefun double hypot (double @var{x}, double @var{y})
294 The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
295 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
296 triangle with sides of length @var{x} and @var{y}, or the distance
297 of the point (@var{x}, @var{y}) from the origin.)  See also the function
298 @code{cabs} in @ref{Absolute Value}.
299 @end deftypefun
300
301 @comment math.h
302 @comment BSD
303 @deftypefun double expm1 (double @var{x})
304 This function returns a value equivalent to @code{exp (@var{x}) - 1}.
305 It is computed in a way that is accurate even if the value of @var{x} is
306 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
307 to subtraction of two numbers that are nearly equal.
308 @end deftypefun
309
310 @comment math.h
311 @comment BSD
312 @deftypefun double log1p (double @var{x})
313 This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
314 It is computed in a way that is accurate even if the value of @var{x} is
315 near zero.
316 @end deftypefun
317
318 @node Hyperbolic Functions
319 @section Hyperbolic Functions
320 @cindex hyperbolic functions
321
322 The functions in this section are related to the exponential functions;
323 see @ref{Exponents and Logarithms}.
324
325 @comment math.h
326 @comment ANSI
327 @deftypefun double sinh (double @var{x})
328 The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
329 mathematically as @w{@code{exp (@var{x}) - exp (-@var{x}) / 2}}.  The
330 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
331 @var{x} is too large; that is, if overflow occurs.
332 @end deftypefun
333
334 @comment math.h
335 @comment ANSI
336 @deftypefun double cosh (double @var{x})
337 The @code{cosh} function returns the hyperbolic cosine of @var{x},
338 defined mathematically as @w{@code{exp (@var{x}) + exp (-@var{x}) / 2}}.
339 The function fails, and sets @code{errno} to @code{ERANGE}, if the value
340 of @var{x} is too large; that is, if overflow occurs.
341 @end deftypefun
342
343 @comment math.h
344 @comment ANSI
345 @deftypefun double tanh (double @var{x})
346 This function returns the hyperbolic tangent of @var{x}, defined
347 mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
348 @end deftypefun
349
350 @cindex inverse hyperbolic functions
351
352 @comment math.h
353 @comment BSD
354 @deftypefun double asinh (double @var{x})
355 This function returns the inverse hyperbolic sine of @var{x}---the
356 value whose hyperbolic sine is @var{x}.
357 @end deftypefun
358
359 @comment math.h
360 @comment BSD
361 @deftypefun double acosh (double @var{x})
362 This function returns the inverse hyperbolic cosine of @var{x}---the
363 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
364 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
365 @end deftypefun
366
367 @comment math.h
368 @comment BSD
369 @deftypefun double atanh (double @var{x})
370 This function returns the inverse hyperbolic tangent of @var{x}---the
371 value whose hyperbolic tangent is @var{x}.  If the absolute value of
372 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
373 @code{HUGE_VAL}.
374 @end deftypefun
375
376 @node Pseudo-Random Numbers
377 @section Pseudo-Random Numbers
378
379 This section describes the GNU facilities for generating a series of
380 pseudo-random numbers.  The numbers generated are not necessarily truly
381 random; typically, the sequences repeat periodically, with the period
382 being a function of the number of bits in the @dfn{seed} or initial
383 state.
384 @cindex random numbers
385 @cindex pseudo-random numbers
386 @cindex seed (for random numbers)
387
388 There are actually two sets of random number functions provided.
389
390 @itemize @bullet
391 @item 
392 The @code{rand} and @code{srand} functions, described in @ref{ANSI
393 Random}, are part of the ANSI C standard.  You can use these functions
394 portably in many C implementations.
395
396 @item 
397 The @code{random} and @code{srandom} functions, described in @ref{BSD
398 Random}, are derived from BSD.  They use a better random number
399 generator (producing numbers that are more random), but are less
400 portable.
401 @c !!! rand/srand just call random/srandom.  It is the same RNG.
402 @end itemize
403
404 For both sets of functions, you can get repeatable sequences of numbers
405 within a single implementation on a single machine type by specifying
406 the same initial seed value for the random number generator.  Other C
407 libraries may produce different sequences of values for the same seed.
408
409
410 @menu
411 * ANSI Random::      @code{rand} and friends.
412 * BSD Random::       @code{random} and friends.
413 @end menu
414
415 @node ANSI Random
416 @subsection ANSI C Random Number Functions
417
418 This section describes the random number functions that are part of
419 the ANSI C standard.
420
421 To use these facilities, you should include the header file
422 @file{stdlib.h} in your program.
423 @pindex stdlib.h
424
425 @comment stdlib.h
426 @comment ANSI
427 @deftypevr Macro int RAND_MAX
428 The value of this macro is an integer constant expression that
429 represents the maximum possible value returned by the @code{rand}
430 function.  In the GNU library, it is @code{037777777}, which is the
431 largest signed integer representable in 32 bits.  In other libraries, it
432 may be as low as @code{32767}.
433 @end deftypevr
434
435 @comment stdlib.h
436 @comment ANSI
437 @deftypefun int rand ()
438 The @code{rand} function returns the next pseudo-random number in the
439 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
440 @end deftypefun
441
442 @comment stdlib.h
443 @comment ANSI
444 @deftypefun void srand (unsigned int @var{seed})
445 This function establishes @var{seed} as the seed for a new series of
446 pseudo-random numbers.  If you call @code{rand} before a seed has been
447 established with @code{srand}, it uses the value @code{1} as a default
448 seed.
449
450 To produce truly random numbers (not just pseudo-random), do @code{srand
451 (time (0))}.
452 @end deftypefun
453
454 @node BSD Random
455 @subsection BSD Random Number Functions
456
457 This section describes a set of random number generation functions that
458 are derived from BSD.  The @code{random} function can generate better
459 random numbers than @code{rand}, because it maintains more bits of
460 internal state.
461 @c !!! false
462
463 The prototypes for these functions are in @file{stdlib.h}.
464 @pindex stdlib.h
465
466 @comment stdlib.h
467 @comment BSD
468 @deftypefun {long int} random ()
469 This function returns the next pseudo-random number in the sequence.
470 The range of values returned is from @code{0} to @code{RAND_MAX}.
471 @end deftypefun
472
473 @comment stdlib.h
474 @comment BSD
475 @deftypefun void srandom (unsigned int @var{seed})
476 The @code{srandom} function sets the seed for the current random number
477 state based on the integer @var{seed}.  If you supply a @var{seed} value
478 of @code{1}, this will cause @code{random} to reproduce the default set
479 of random numbers.
480
481 To produce truly random numbers (not just pseudo-random), do
482 @code{srandom (time (0))}.
483 @end deftypefun
484
485 @comment stdlib.h
486 @comment BSD
487 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
488 The @code{initstate} function is used to initialize the random number
489 generator state.  The argument @var{state} is an array of @var{size}
490 bytes, used to hold the state information.  The size must be at least 8
491 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
492 the @var{state} array, the better.
493
494 The return value is the previous value of the state information array.
495 You can use this value later as an argument to @code{setstate} to
496 restore that state.
497 @end deftypefun
498
499 @comment stdlib.h
500 @comment BSD
501 @deftypefun {void *} setstate (void *@var{state})
502 The @code{setstate} function restores the random number state
503 information @var{state}.  The argument must have been the result of
504 a previous call to @var{initstate} or @var{setstate}.  
505
506 The return value is the previous value of the state information array.
507 You can use thise value later as an argument to @code{setstate} to
508 restore that state.
509 @end deftypefun