Initial revision
[kopensolaris-gnu/glibc.git] / manual / math.texi
1 @node Mathematics
2 @chapter Mathematics --- @file{<math.h>}
3 @pindex <math.h>
4
5 This chapter contains information about functions for performing
6 mathematical computations, such as trigonometric functions.  Most
7 of these functions have prototypes declared in the header file
8 @file{<math.h>}.
9
10 @strong{Incomplete:}  This chapter doesn't have any examples.
11
12 @menu
13 * Domain and Range Errors::             How overflow conditions and the like
14                                          are reported.
15 * Trigonometric Functions::             Sine, cosine, and tangent.
16 * Inverse Trigonometric Functions::     Arc sine, arc cosine, and arc tangent.
17 * Exponentiation and Logarithms::       Also includes square root.
18 * Hyperbolic Functions::                Hyperbolic sine and friends.
19 * Normalization Functions::             Hacks for radix-2 representations.
20 * Rounding and Remainder Functions::    Determinining the integer and
21                                          fractional parts of a float.
22 * Pseudo-Random Numbers::               Functions for generating pseudo-random
23                                          numbers.
24 * Integer Division::                    Functions for performing integer
25                                          division.
26 * Absolute Value::                      Absolute value functions.
27 * Parsing of Numbers::                  Functions for ``reading'' numbers
28                                          from strings.
29 @end menu
30
31 @node Domain and Range Errors
32 @section Domain and Range Errors
33
34 @cindex domain error
35 Many of the functions listed in this chapter are defined mathematically
36 over a domain that is only a subset of real numbers.  For example, the
37 @code{acos} function is defined over the domain between @code{-1} and
38 @code{1}.  If you pass an argument to one of these functions that is
39 outside the domain over which it is defined, the function returns
40 an unspecified value and sets @code{errno} to @code{EDOM} to indicate
41 a @dfn{domain error}.
42
43 Some of these functions are defined mathematically to result in a
44 complex value over parts of their domains.  The most familiar example of
45 this is taking the square root of a negative number.  Since the C
46 language has no support for complex numbers, this is treated like a
47 domain 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 result
52 is too large to be represented, the value of the macro @code{HUGE_VAL}
53 is returned (with the appropriate sign), and @code{errno} is set to
54 @code{ERANGE} to indicate a @dfn{range error}.  If the magnitude of the
55 result is too small, a value of zero is returned instead.  In the case
56 of underflow, @code{errno} might or might not be set to @code{ERANGE}.
57
58 None of these functions ever generate externally visible exceptions
59 as a result of domain or range errors.  In particular, this means that
60 you won't see @code{SIGFPE} signals generated within these functions.
61 @xref{Signal Handling}, for more information about signals.
62
63 All of the functions that operate on floating-point numbers accept
64 arguments and return results of type @code{double}.  In future revisions
65 of the ANSI C standard, additional functions may be added that operate
66 on @code{float} and @code{long double} values.  For example, @code{cosf}
67 and @code{cosl} would be versions of the @code{cos} function that
68 operate on @code{float} and @code{long double} arguments, respectively.
69 In the meantime, you should avoid using these names yourself.
70 @xref{Reserved Names}.
71
72 @defvr Macro HUGE_VAL
73 This macro expands into a (possibly non-constant) expression of type
74 @code{double} representing a very large positive number.  This is
75 typically either the largest representable floating-point number, or a
76 value indicating infinity if the floating-point representation has one.
77 (The IEEE floating-point does have such a reserved value.)
78
79 The value of this macro is used as the return value from various 
80 mathematical functions in overflow situations.
81 @end defvr
82
83 For more information about floating-point representations and limits,
84 @xref{Floating-Point Limits}.  In particular, the macro @code{DBL_MAX}
85 might be more appropriate than @code{HUGE_VAL} for many uses.
86
87
88 @node Trigonometric Functions
89 @section Trigonometric Functions
90
91 @strong{Incomplete:}  What font convention should be used for things
92 like ``pi'' and ``e''?
93
94 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
95 The arguments to all of these functions are specified in radians; recall
96 that pi radians is equivalent to 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 @samp{acos (-1.0)}.
108
109
110 @deftypefun double sin (double @var{x})
111 This function returns the sine of @var{x}, which is given in radians.
112 The return value is in the range @code{-1} to @code{1}.
113 @end deftypefun
114
115 @deftypefun double cos (double @var{x})
116 This function returns the cosine of @var{x}, which is given in radians.
117 The return value is in the range @code{-1} to @code{1}.
118 @end deftypefun
119
120 @deftypefun double tan (double @var{x})
121 This function returns the tangent of @var{x}, which is given in radians.
122
123 The following @code{errno} error conditions are defined for this function:
124
125 @table @code
126 @item ERANGE
127 Mathematically, the tangent function has singularities at odd multiples of
128 pi/2.  If the argument @var{x} is too close to one of these singularities,
129 @code{tan} sets this error condition and returns either positive or
130 negative @code{HUGE_VAL}.
131 @end table
132 @end deftypefun
133
134
135 @node Inverse Trigonometric Functions
136 @section Inverse Trigonometric Functions
137
138 These are the usual arc sine, arc cosine, and arc tangent functions.
139
140 @deftypefun double asin (double @var{x})
141 This function computes the arc sine of @var{x}.  The return value is
142 given in radians and is in the range -pi/2 to pi/2 (inclusive).
143
144 The following @code{errno} error conditions are defined for this function:
145
146 @table @code
147 @item EDOM
148 The argument @var{x} is out of range.  The arc sine function is defined
149 mathematically only over the domain -1 to 1.
150 @end table
151 @end deftypefun
152
153 @deftypefun double acos (double @var{x})
154 This function computes the arc cosine of @var{x}.  The return value is
155 given in radians and is in the range 0 to pi (inclusive).
156
157 The following @code{errno} error conditions are defined for this function:
158
159 @table @code
160 @item EDOM
161 The argument @var{x} is out of range.  The arc cosine function is defined
162 mathematically only over the domain -1 to 1.
163 @end table
164 @end deftypefun
165
166
167 @deftypefun double atan (double @var{x})
168 This function returns the arc tangent of @var{x}.  The return value is
169 given in radians and is in the range -pi/2 to pi/2 (inclusive).
170 @end deftypefun
171
172 @deftypefun double atan2 (double @var{y}, double @var{x})
173 This is the two argument arc tangent function.  It is similar to computing
174 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
175 are used to determine the quadrant of the result, and @var{x} is
176 permitted to be zero.  The return value is given in radians and is in
177 the range -pi to pi (inclusive).
178
179 The following @code{errno} error conditions are defined for this function:
180
181 @table @code
182 @item EDOM
183 Both the @var{x} and @var{y} arguments are zero; the value of the
184 function is not defined in this case.
185 @end table
186 @end deftypefun
187
188
189 @node Exponentiation and Logarithms
190 @section Exponentiation and Logarithms
191
192 @deftypefun double exp (double @var{x})
193 The @code{exp} function returns the value of e (the base of natural
194 logarithms) raised to power @var{x}.
195
196 The following @code{errno} error conditions are defined for this function:
197
198 @table @code
199 @item ERANGE
200 The magnitude of the result is too large to be representable.
201 @end table
202 @end deftypefun
203
204 @deftypefun double log (double @var{x})
205 This function returns the natural logarithm of @var{x}.
206
207 The following @code{errno} error conditions are defined for this function:
208
209 @table @code
210 @item EDOM
211 The log function is defined mathematically to return a non-complex
212 result only on positive arguments.  This error is used to report a
213 negative argument @var{x}.
214
215 @item ERANGE
216 The result of the function on an argument of zero is not defined.
217 @end table
218 @end deftypefun
219
220 @deftypefun double log10 (double @var{x})
221 This function returns the base-10 logarithm of @var{x}.  Except for the
222 different base, it is similar to the @code{log} function.
223 @end deftypefun
224
225 @deftypefun double pow (double @var{base}, double @var{power})
226 This is a general exponentiation function, returning @var{base} raised
227 to @var{power}.
228
229 The following @code{errno} error conditions are defined for this function:
230
231 @table @code
232 @item EDOM
233 The argument @var{base} is negative and @var{power} is not an integral
234 value.  Mathematically, the result would be a complex number in this case.
235
236 @item ERANGE
237 An underflow or overflow condition was detected in the result.
238 @end table
239 @end deftypefun
240
241 @deftypefun double sqrt (double @var{x})
242 This function returns the nonnegative square root of @var{x}.
243
244 The following @code{errno} error conditions are defined for this function:
245
246 @table @code
247 @item EDOM
248 The argument @var{x} is negative.  Mathematically, the square root would
249 be a complex number.
250 @end table
251 @end deftypefun
252
253
254
255 @node Hyperbolic Functions
256 @section Hyperbolic Functions
257
258 The functions in this section are related to the exponential and
259 functions; @pxref{Exponentiation and Logarithms}.
260
261 @deftypefun double sinh (double @var{x})
262 The @code{sinh} function returns the hyperbolic sine of @var{x}.  The
263 following @code{errno} error conditions are defined for this function:
264
265 @table @code
266 @item ERANGE
267 The value of the argument @var{x} is too large; an overflow condition
268 was detected.
269 @end table
270 @end deftypefun
271
272 @deftypefun double cosh (double @var{x})
273 The @code{cosh} function returns the hyperbolic cosine of @var{x}.  The
274 following @code{errno} error conditions are defined for this function:
275
276 @table @code
277 @item ERANGE
278 The value of the argument @var{x} is too large; an overflow condition
279 was detected.
280 @end table
281 @end deftypefun
282
283 @deftypefun double tanh (double @var{x})
284 This function returns the hyperbolic tangent of @var{x}.
285 @end deftypefun
286
287
288 @node Normalization Functions
289 @section Normalization Functions
290
291 The functions described in this section are primarily provided as a way
292 to efficiently perform certain low-level manipulations on floating point
293 numbers that are represented internally using a binary radix;
294 @pxref{Floating-Point Representation}.  These functions are required to
295 have equivalent behavior even if the representation does not use a radix
296 of 2, but of course they are unlikely to be particularly efficient in
297 those cases.
298
299 @deftypefun double frexp (double @var{value}, int *@var{exponent})
300 The @code{frexp} function is used to normalize the number @var{value}.
301
302 If the argument @var{value} is not zero, the return value is a
303 floating-point number with magnitude in the range 1/2 (inclusive) to 1
304 (exclusive).  The corresponding exponent is stored in the location
305 pointed at by @var{exponent}; the return value multiplied by 2 raised to
306 this exponent is equal to the original number @var{value}.
307
308 If @var{value} is zero, then both parts of the result are zero.
309 @end deftypefun
310
311 @deftypefun double ldexp (dobule @var{value}, int @var{exponent})
312 This function returns the result of multiplying the floating-point
313 number @var{value} by 2 raised to the power @var{exponent}.  (It can
314 be used to reassemble floating-point numbers that were taken apart
315 by @code{frexp}.)
316 @end deftypefun
317
318
319 @node Rounding and Remainder Functions
320 @section Rounding and Remainder Functions
321
322 The functions listed here perform operations such as rounding, 
323 truncation, and remainder computation.
324
325 You can also convert floating-point numbers to integers simply by
326 casting them to @code{int}.  This discards the fractional part,
327 effectively rounding towards zero.  However, this only works if the
328 result can actually be represented as an @code{int} --- for very large
329 numbers, the result is undefined.  The functions listed here return the
330 result as a @code{double} instead to get around this problem.
331
332 @deftypefun double ceil (double @var{x})
333 The @code{ceil} function rounds @var{x} upwards to the nearest integer,
334 returning that value as a @code{double}.
335 @end deftypefun
336
337 @deftypefun double floor (double @var{x})
338 The @code{ceil} function rounds @var{x} downwards to the nearest
339 integer, returning that value as a @code{double}.
340 @end deftypefun
341
342 @deftypefun double modf (double @var{value}, double *@var{integer_part})
343 This function breaks the argument @var{value} into an integer part and a
344 fractional part.  Each of the parts has the same sign as the original
345 @var{value}, so the rounding of the integer part is towards zero.  The
346 integer part is stored at the location pointed at by @var{integer_part},
347 and the fractional part is returned.
348 @end deftypefun
349
350
351 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
352 This function computes the remainder from dividing @var{numerator} by
353 @var{denominator}.  The result has the same sign as the @var{numerator}
354 and has magnitude less than the magnitude of the @var{denominator}.
355 (Recall that the built-in @samp{%} operator isn't defined on
356 floating-point values.)
357
358 The following @code{errno} error conditions are defined for this function:
359
360 @table @code
361 @item EDOM
362 The @var{denominator} is zero.
363 @end table
364 @end deftypefun
365
366
367 @node Pseudo-Random Numbers
368 @section Pseudo-Random Numbers
369
370 This section describes the standard facilities for generating a series
371 of pseudo-random numbers.  The numbers generated by the @code{rand}
372 function are not required to be truly random; typically, the sequences
373 repeat periodically, with the period being a function of the number
374 of bits in the @dfn{seed} or initial state.
375 @cindex random numbers
376 @cindex pseudo-random numbers
377 @cindex seed (for random numbers)
378
379 Within a single implementation, you can get the same series of numbers
380 by specifying the same initial seed value with the @code{srand}
381 function.  However, the actual algorithm used to generate such a series
382 is implementation-dependent.  Therefore, your program cannot use these
383 facilities if you want to get reproducible behavior across multiple
384 implementations.
385
386 To use these facilities, you should include the header file
387 @file{<stdlib.h>} in your program.
388
389 @defvr Macro RAND_MAX
390 The value of this macro is an integer constant expression that
391 represents the maximum possible value returned by the @code{rand}
392 function.  It is guaranteed to be at least @code{32767}.
393 @end defvr
394
395 @deftypefun int rand (void)
396 The @code{rand} function returns the next pseudo-random number in the
397 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
398 @end deftypefun
399
400 @deftypefun void srand (unsigned int @var{seed})
401 This function establishes @var{seed} as the seed for a new series of
402 pseudo-random numbers.  If @code{rand} is called before a seed has been
403 established with @code{srand}, it is equivalent to having specified an
404 initial seed value of @code{1}.
405 @end deftypefun
406
407
408 @node Integer Division
409 @section Integer Division
410
411 This section describes functions for performing integer division.
412 To use these facilities, you should include the header file
413 @file{<stdlib.h>} in your program.
414
415 These functions are not necessarily equivalent to the division performed
416 by the built-in @code{/} and @code{%} operators.  While the built-in
417 division operator is permitted to round in either direction if the
418 quotient is negative, the @code{div} and @code{ldiv} functions are
419 required to round towards zero.  It is also required that these
420 functions return a result such that @code{quot*@var{denominator} + rem}
421 be equal to @var{numerator}.
422
423 @deftp {Data Type} div_t
424 This is a structure type used to hold the result returned by the @code{div}
425 function.  It has the following members:
426
427 @table @code
428 @item {int quot}
429 The quotient from the division.
430
431 @item {int rem}
432 The remainder from the division.
433 @end table
434 @end deftp
435
436 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
437 This function @code{div} computes the quotient and remainder from
438 the division of @var{numerator} by @var{denominator}, returning the
439 result in a structure of type @code{div_t}.
440
441 If the result cannot be represented (as in a division by zero), the
442 behavior is undefined.
443 @end deftypefun
444
445
446 @deftp {Data Type} ldiv_t
447 This is a structure type used to hold the result returned by the @code{ldiv}
448 function.  It has the following members:
449
450 @table @code
451 @item {long int quot}
452 The quotient from the division.
453
454 @item {long int rem}
455 The remainder from the division.
456 @end table
457
458 (This is identical to the type @code{div_t} except that the components
459 are of type @code{long int} rather than @code{int}.)
460 @end deftp
461
462 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
463 The @code{ldiv} function is similar to @code{div}, except that the
464 arguments are of type @code{long int} and the result is returned as a
465 structure of type @code{ldiv}.
466 @end deftypefun
467
468
469 @node Absolute Value
470 @section Absolute Value
471
472 These functions are provided for obtaining the absolute value of
473 integer values.  Prototypes for @code{abs} and @code{abs} are declared
474 in @file{<stdlib.h>}; @code{fabs} is declared in @file{<math.h>}.
475
476 @deftypefun int abs (int @var{number})
477 This function returns the absolute value (or magnitude) of @var{number}.
478 In a two's complement integer representation, the absolute value of
479 @code{INT_MIN} (the smallest possible @code{int}) cannot be represented;
480 in this case, the behavior of @code{abs} is undefined.
481 @end deftypefun
482
483 @deftypefun {long int} labs (long int @var{number})
484 This is similar to @code{abs}, except that both the argument and result
485 are of type @code{long int} rather than @code{int}.
486 @end deftypefun
487
488 @deftypefun double fabs (double @var{number})
489 This function returns the absolute value of the floating-point number
490 @var{number}.
491 @end deftypefun
492
493 @node Parsing of Numbers
494 @section Parsing of Numbers
495 @cindex parsing of numbers
496 @cindex string conversion
497 @cindex number syntax
498
499 This section describes functions for ``reading'' integer and
500 floating-point numbers from a string.  In many cases, it is more
501 appropriate to use @code{sscanf} or one of the related functions;
502 @pxref{Formatted Input}.  The syntax recognized by the formatted input
503 functions for the numeric conversions is exactly the same as the syntax
504 recognized by the functions described in this section.
505
506 These functions are declared in @file{<stdlib.h>}.
507
508 @menu
509 * Parsing of Integers::         Functions for conversion of integer values.
510 * Parsing of Floats::           Functions for conversion of floating-point
511                                  values.
512 @end menu
513
514 @node Parsing of Integers
515 @subsection Parsing of Integers
516 @cindex parsing of integers
517
518 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
519 The @code{strtol} (``string-to-long'') function converts the initial
520 part of @var{string} to a signed integer, which is returned as a value
521 of type @code{long int}.  
522
523 This function attempts to decompose @var{string} as follows:
524
525 @itemize @bullet
526 @item 
527 A (possibly empty) sequence of whitespace characters, as determined by
528 the @code{isspace} function (@pxref{Classification of Characters}).
529 These are discarded.
530
531 @item 
532 An optional plus or minus sign (@samp{+} or @samp{-}).
533
534 @item 
535 A nonempty sequence of digits in the radix specified by @var{base}.  If
536 @var{base} is zero, decimal radix is assumed unless the series of digits
537 begins with @samp{0} (specifying octal radix), or @samp{0x} or @samp{0X}
538 (specifying hexadecimal radix); in other words, the same syntax that is
539 used for integer constants in the C language is recognized.  Otherwise
540 @var{base} must have a value between @code{2} and @code{35}.  If
541 @var{base} is @code{16}, the digits may optionally be preceeded by
542 @samp{0x} or @samp{0X}.
543
544 @item 
545 Any remaining characters in the string.  If @var{tailptr} is not a null
546 pointer, a pointer to this tail of the string is stored in the object
547 it points to.
548 @end itemize
549
550 If the string is empty, contains only whitespace, or does not contain an
551 initial substring that has the expected syntax for an integer in the
552 specified @var{base}, no conversion is performed.  In this case,
553 @code{strtol} returns a value of zero and the value returned in
554 @var{tailptr} is the value of @var{string}.
555
556 In a locale other than the standard @code{"C"} locale, this function
557 may recognize additional implementation-dependent syntax.
558
559 If the string has valid syntax for an integer but the value is not
560 representable because of overflow, @code{strtol} returns either
561 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Integer Representation
562 Limits}), as appropriate for the sign of the value.
563
564 The following @code{errno} error conditions are defined for this
565 function:
566
567 @table @code
568 @item ERANGE
569 An overflow condition was detected.
570 @end table
571 @end deftypefun
572
573 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
574 The @code{strtoul} (``string-to-unsigned-long'') function is similar to
575 @code{strtol} except that it returns its value as an object of type
576 @code{unsigned long int}.  The value returned in case of overflow is
577 @code{ULONG_MAX} (@pxref{Integer Representation Limits}).
578 @end deftypefun
579
580 @deftypefun {long int} atol (const char *@var{string})
581 This function is similar to the @code{strtol} function with a @var{base}
582 argument of @code{10}, except that it need not detect overflow errors.
583 The @code{atol} function is provided mostly for compatibility with
584 existing code; using @code{strtol} is considered better style.
585 @end deftypefun
586
587 @deftypefun int atoi (const char *@var{string})
588 This function is similar to the @code{atol} function, except that
589 returns its value as an @code{int} rather than @code{long int}.  The
590 @code{atoi} function is also considered obsolete; use @code{strtol}
591 instead.
592 @end deftypefun
593
594
595 @node Parsing of Floats
596 @subsection Parsing of Floats
597
598 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
599 The @code{strtod} (``string-to-double'') function converts the initial
600 part of @var{string} to a floating-point number, which is returned as a
601 value of type @code{double}.  
602
603 This function attempts to decompose @var{string} as follows:
604
605 @itemize @bullet
606 @item 
607 A (possibly empty) sequence of whitespace characters, as determined
608 by the @code{isspace} function.  These are discarded.
609
610 @item
611 An optional plus or minus sign (@samp{+} or @samp{-}).
612
613 @item
614 A nonempty sequence of digits optionally containing a decimal-point
615 character (@samp{.}).
616
617 @item
618 An optional exponent part, consisting of a character @samp{e} or
619 @samp{E}, an optional sign, and a sequence of digits.
620
621 @item
622 Any remaining characters in the string.  If @var{tailptr} is not a null
623 pointer, a pointer to this tail of the string is stored in the object it
624 points to.
625 @end itemize
626
627 If the string is empty, contains only whitespace, or does not contain
628 an initial substring that has the expected syntax for a floating-point
629 number, no conversion is performed.  In this case, @code{strtod} returns
630 a value of zero and the value returned in @var{tailptr} is the value of
631 @var{string}.
632
633 In a locale other than the standard @code{"C"} locale, this function
634 may recognize additional implementation-dependent syntax.
635
636 If the string has valid syntax for a floating-point number but the value
637 is not representable because of overflow, @code{strtod} returns either
638 positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
639 the sign of the value.  Similarly, if the value is not representable
640 because of underflow, @code{strtod} returns zero.
641
642 The following @code{errno} error conditions are defined for this
643 function:
644
645 @table @code
646 @item ERANGE
647 An overflow or underflow condition was detected.
648 @end table
649 @end deftypefun
650
651 @deftypefun double atof (const char *@var{string})
652 This function is similar to the @code{strtod} function, except that it
653 need not detect overflow and underflow errors.  The @code{atof} function
654 is provided mostly for compatibility with existing code; using
655 @code{strtod} is considered better style.
656 @end deftypefun
657