(_hurd_sig_post): __sig_post renamed to __msg_sig_post.
[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 IEEE floating point, functions reporting error
40 @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 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 @smallexample
103 #define PI 3.14159265358979323846264338327
104 @end smallexample
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 BSD
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 representable 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}, whose 
347 mathematical definition is @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 @cindex random numbers
379 @cindex pseudo-random numbers
380 @cindex seed (for random numbers)
381
382 This section describes the GNU facilities for generating a series of
383 pseudo-random numbers.  The numbers generated are not truly random;
384 typically, they form a sequence that repeats periodically, with a
385 period so large that you can ignore it for ordinary purposes.  The
386 random number generator works by remembering at all times a @dfn{seed}
387 value which it uses to compute the next random number and also to
388 compute a new seed.
389
390 Although the generated numbers look unpredictable within one run of a
391 program, the sequence of numbers is @emph{exactly the same} from one run
392 to the next.  This is because the initial seed is always the same.  This
393 is convenient when you are debugging a program, but it is unhelpful if
394 you want the program to behave unpredictably.  If you want truly random
395 numbers, not just pseudo-random, specify a seed based on the current
396 time.
397
398 You can get repeatable sequences of numbers on a particular machine type
399 by specifying the same initial seed value for the random number
400 generator.  There is no standard meaning for a particular seed value;
401 the same seed, used in different C libraries or on different CPU types,
402 will give you different random numbers.
403
404 The GNU library supports the standard ANSI C random number functions
405 plus another set derived from BSD.  We recommend you use the standard
406 ones, @code{rand} and @code{srand}.
407
408 @menu
409 * ANSI Random::      @code{rand} and friends.
410 * BSD Random::       @code{random} and friends.
411 @end menu
412
413 @node ANSI Random
414 @subsection ANSI C Random Number Functions
415
416 This section describes the random number functions that are part of
417 the ANSI C standard.
418
419 To use these facilities, you should include the header file
420 @file{stdlib.h} in your program.
421 @pindex stdlib.h
422
423 @comment stdlib.h
424 @comment ANSI
425 @deftypevr Macro int RAND_MAX
426 The value of this macro is an integer constant expression that
427 represents the maximum possible value returned by the @code{rand}
428 function.  In the GNU library, it is @code{037777777}, which is the
429 largest signed integer representable in 32 bits.  In other libraries, it
430 may be as low as @code{32767}.
431 @end deftypevr
432
433 @comment stdlib.h
434 @comment ANSI
435 @deftypefun int rand ()
436 The @code{rand} function returns the next pseudo-random number in the
437 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
438 @end deftypefun
439
440 @comment stdlib.h
441 @comment ANSI
442 @deftypefun void srand (unsigned int @var{seed})
443 This function establishes @var{seed} as the seed for a new series of
444 pseudo-random numbers.  If you call @code{rand} before a seed has been
445 established with @code{srand}, it uses the value @code{1} as a default
446 seed.
447
448 To produce truly random numbers (not just pseudo-random), do @code{srand
449 (time (0))}.
450 @end deftypefun
451
452 @node BSD Random
453 @subsection BSD Random Number Functions
454
455 This section describes a set of random number generation functions that
456 are derived from BSD.  There is no advantage to using these functions
457 with the GNU C library; we support them for BSD compatibility only.
458
459 The prototypes for these functions are in @file{stdlib.h}.
460 @pindex stdlib.h
461
462 @comment stdlib.h
463 @comment BSD
464 @deftypefun {long int} random ()
465 This function returns the next pseudo-random number in the sequence.
466 The range of values returned is from @code{0} to @code{RAND_MAX}.
467 @end deftypefun
468
469 @comment stdlib.h
470 @comment BSD
471 @deftypefun void srandom (unsigned int @var{seed})
472 The @code{srandom} function sets the seed for the current random number
473 state based on the integer @var{seed}.  If you supply a @var{seed} value
474 of @code{1}, this will cause @code{random} to reproduce the default set
475 of random numbers.
476
477 To produce truly random numbers (not just pseudo-random), do
478 @code{srandom (time (0))}.
479 @end deftypefun
480
481 @comment stdlib.h
482 @comment BSD
483 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
484 The @code{initstate} function is used to initialize the random number
485 generator state.  The argument @var{state} is an array of @var{size}
486 bytes, used to hold the state information.  The size must be at least 8
487 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
488 the @var{state} array, the better.
489
490 The return value is the previous value of the state information array.
491 You can use this value later as an argument to @code{setstate} to
492 restore that state.
493 @end deftypefun
494
495 @comment stdlib.h
496 @comment BSD
497 @deftypefun {void *} setstate (void *@var{state})
498 The @code{setstate} function restores the random number state
499 information @var{state}.  The argument must have been the result of
500 a previous call to @var{initstate} or @var{setstate}.  
501
502 The return value is the previous value of the state information array.
503 You can use thise value later as an argument to @code{setstate} to
504 restore that state.
505 @end deftypefun