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