Incorporated review comments from RMS.
[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 * Predicates on Floats::                Some miscellaneous test functions.
28 * Parsing of Numbers::                  Functions for ``reading'' numbers
29                                          from strings.
30 @end menu
31
32 @node Domain and Range Errors
33 @section Domain and Range Errors
34
35 @cindex domain error
36 Many of the functions listed in this chapter are defined mathematically
37 over a domain that is only a subset of real numbers.  For example, the
38 @code{acos} function is defined over the domain between @code{-1} and
39 @code{1}.  If you pass an argument to one of these functions that is
40 outside the domain over which it is defined, the function returns
41 an unspecified value and sets @code{errno} to @code{EDOM} to indicate
42 a @dfn{domain error}.
43
44 Some of these functions are defined mathematically to result in a
45 complex value over parts of their domains.  The most familiar example of
46 this is taking the square root of a negative number.  Since the C
47 language has no support for complex numbers, this is treated like a
48 domain error.
49
50 @cindex range error
51 A related problem is that the mathematical result of a function may not
52 be representable as a floating point number.  If magnitude of the result
53 is too large to be represented, the value of the macro @code{HUGE_VAL}
54 is returned (with the appropriate sign), and @code{errno} is set to
55 @code{ERANGE} to indicate a @dfn{range error}.  If the magnitude of the
56 result is too small, a value of zero is returned instead.  In the case
57 of underflow, @code{errno} might or might not be set to @code{ERANGE}.
58
59 None of these functions ever generate externally visible exceptions
60 as a result of domain or range errors.  In particular, this means that
61 you won't see @code{SIGFPE} signals generated within these functions.
62 @xref{Signal Handling}, for more information about signals.
63
64 All of the functions that operate on floating-point numbers accept
65 arguments and return results of type @code{double}.  In future revisions
66 of the ANSI C standard, additional functions may be added that operate
67 on @code{float} and @code{long double} values.  For example, @code{cosf}
68 and @code{cosl} would be versions of the @code{cos} function that
69 operate on @code{float} and @code{long double} arguments, respectively.
70 In the meantime, you should avoid using these names yourself.
71 @xref{Reserved Names}.
72
73 @comment math.h
74 @comment ANSI
75 @defvr Macro HUGE_VAL
76 This macro expands into a (possibly non-constant) expression of type
77 @code{double} representing a very large positive number.  This is
78 typically either the largest representable floating-point number, or a
79 value indicating infinity if the floating-point representation has one.
80 (The IEEE floating-point does have such a reserved value.)
81
82 The value of this macro is used as the return value from various 
83 mathematical functions in overflow situations.
84 @end defvr
85
86 For more information about floating-point representations and limits,
87 @xref{Floating-Point Limits}.  In particular, the macro @code{DBL_MAX}
88 might be more appropriate than @code{HUGE_VAL} for many uses.
89
90
91 @node Trigonometric Functions
92 @section Trigonometric Functions
93
94 @strong{Incomplete:}  What font convention should be used for things
95 like ``pi'' and ``e''?
96
97 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
98 The arguments to all of these functions are specified in radians; recall
99 that pi radians is equivalent to 180 degrees.  
100
101 @cindex pi (trigonometric constant)
102 The math library doesn't define a symbolic constant for pi, but you can
103 define your own if you need one:
104
105 @example
106 #define PI 3.14159265358979323846264338327
107 @end example
108
109 @noindent
110 You can also compute the value of pi with the expression @samp{acos (-1.0)}.
111
112
113 @comment math.h
114 @comment ANSI
115 @deftypefun double sin (double @var{x})
116 This function returns the sine 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 @comment math.h
121 @comment ANSI
122 @deftypefun double cos (double @var{x})
123 This function returns the cosine of @var{x}, which is given in radians.
124 The return value is in the range @code{-1} to @code{1}.
125 @end deftypefun
126
127 @comment math.h
128 @comment ANSI
129 @deftypefun double tan (double @var{x})
130 This function returns the tangent of @var{x}, which is given in radians.
131
132 The following @code{errno} error conditions are defined for this function:
133
134 @table @code
135 @item ERANGE
136 Mathematically, the tangent function has singularities at odd multiples of
137 pi/2.  If the argument @var{x} is too close to one of these singularities,
138 @code{tan} sets this error condition and returns either positive or
139 negative @code{HUGE_VAL}.
140 @end table
141 @end deftypefun
142
143
144 @node Inverse Trigonometric Functions
145 @section Inverse Trigonometric Functions
146
147 These are the usual arc sine, arc cosine, and arc tangent functions.
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}.  The return value is
153 given in radians and is in the range -pi/2 to pi/2 (inclusive).
154
155 The following @code{errno} error conditions are defined for this function:
156
157 @table @code
158 @item EDOM
159 The argument @var{x} is out of range.  The arc sine function is defined
160 mathematically only over the domain -1 to 1.
161 @end table
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}.  The return value is
168 given in radians and is in the range 0 to pi (inclusive).
169
170 The following @code{errno} error conditions are defined for this function:
171
172 @table @code
173 @item EDOM
174 The argument @var{x} is out of range.  The arc cosine function is defined
175 mathematically only over the domain -1 to 1.
176 @end table
177 @end deftypefun
178
179
180 @comment math.h
181 @comment ANSI
182 @deftypefun double atan (double @var{x})
183 This function returns the arc tangent of @var{x}.  The return value is
184 given in radians and is in the range -pi/2 to pi/2 (inclusive).
185 @end deftypefun
186
187 @comment math.h
188 @comment ANSI
189 @deftypefun double atan2 (double @var{y}, double @var{x})
190 This is the two argument arc tangent function.  It is similar to computing
191 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
192 are used to determine the quadrant of the result, and @var{x} is
193 permitted to be zero.  The return value is given in radians and is in
194 the range -pi to pi (inclusive).
195
196 The following @code{errno} error conditions are defined for this function:
197
198 @table @code
199 @item EDOM
200 Both the @var{x} and @var{y} arguments are zero; the value of the
201 function is not defined in this case.
202 @end table
203 @end deftypefun
204
205
206 @node Exponentiation and Logarithms
207 @section Exponentiation and Logarithms
208
209 @comment math.h
210 @comment ANSI
211 @deftypefun double exp (double @var{x})
212 The @code{exp} function returns the value of e (the base of natural
213 logarithms) raised to power @var{x}.
214
215 The following @code{errno} error conditions are defined for this function:
216
217 @table @code
218 @item ERANGE
219 The magnitude of the result is too large to be representable.
220 @end table
221 @end deftypefun
222
223 @comment math.h
224 @comment ANSI
225 @deftypefun double log (double @var{x})
226 This function returns the natural logarithm of @var{x}.
227
228 The following @code{errno} error conditions are defined for this function:
229
230 @table @code
231 @item EDOM
232 The log function is defined mathematically to return a non-complex
233 result only on positive arguments.  This error is used to report a
234 negative argument @var{x}.
235
236 @item ERANGE
237 The result of the function on an argument of zero is not defined.
238 @end table
239 @end deftypefun
240
241 @comment math.h
242 @comment ANSI
243 @deftypefun double log10 (double @var{x})
244 This function returns the base-10 logarithm of @var{x}.  Except for the
245 different base, it is similar to the @code{log} function.
246 @end deftypefun
247
248 @comment math.h
249 @comment ANSI
250 @deftypefun double pow (double @var{base}, double @var{power})
251 This is a general exponentiation function, returning @var{base} raised
252 to @var{power}.
253
254 The following @code{errno} error conditions are defined for this function:
255
256 @table @code
257 @item EDOM
258 The argument @var{base} is negative and @var{power} is not an integral
259 value.  Mathematically, the result would be a complex number in this case.
260
261 @item ERANGE
262 An underflow or overflow condition was detected in the result.
263 @end table
264 @end deftypefun
265
266 @comment math.h
267 @comment ANSI
268 @deftypefun double sqrt (double @var{x})
269 This function returns the nonnegative square root of @var{x}.
270
271 The following @code{errno} error conditions are defined for this function:
272
273 @table @code
274 @item EDOM
275 The argument @var{x} is negative.  Mathematically, the square root would
276 be a complex number.
277 @end table
278 @end deftypefun
279
280 @comment math.h
281 @comment GNU
282 @deftypefun double cbrt (double @var{x})
283 This function returns the cube root of @var{x}.
284 @end deftypefun
285
286 @comment math.h
287 @comment GNU
288 @deftypefun double hypot (double @var{x}, double @var{y})
289 The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
290 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
291 triangle with sides of length @var{x} and @var{y}, or the distance
292 of the point (@var{x}, @var{y}) from the origin.)
293 @end deftypefun
294
295 @comment math.h
296 @comment GNU
297 @deftypefun double cabs (struct @{ double x, y; @} @var{z})
298 The @code{cabs} function is similar to @code{hypot}, but the argument
299 is specified as a @code{struct} representing a complex number.
300 @end deftypefun
301
302
303 @comment math.h
304 @comment GNU
305 @deftypefun double expm1 (double @var{x})
306 This function returns a value equivalent to @code{exp (@var{x}) - 1}.
307 It is computed in a way that is accurate even if the value of @var{x}
308 is very small.
309 @end deftypefun
310
311
312 @comment math.h
313 @comment GNU
314 @deftypefun double log1p (double @var{x})
315 This function returns a value equivalent to @code{log (1 + @var{x})}.
316 It is computed in a way that is accurate even if the value of @var{x}
317 is very small.
318 @end deftypefun
319
320
321
322 @node Hyperbolic Functions
323 @section Hyperbolic Functions
324
325 The functions in this section are related to the exponential and
326 functions; @pxref{Exponentiation and Logarithms}.
327
328 @comment math.h
329 @comment ANSI
330 @deftypefun double sinh (double @var{x})
331 The @code{sinh} function returns the hyperbolic sine of @var{x}.  The
332 following @code{errno} error conditions are defined for this function:
333
334 @table @code
335 @item ERANGE
336 The value of the argument @var{x} is too large; an overflow condition
337 was detected.
338 @end table
339 @end deftypefun
340
341 @comment math.h
342 @comment ANSI
343 @deftypefun double cosh (double @var{x})
344 The @code{cosh} function returns the hyperbolic cosine of @var{x}.  The
345 following @code{errno} error conditions are defined for this function:
346
347 @table @code
348 @item ERANGE
349 The value of the argument @var{x} is too large; an overflow condition
350 was detected.
351 @end table
352 @end deftypefun
353
354 @comment math.h
355 @comment ANSI
356 @deftypefun double tanh (double @var{x})
357 This function returns the hyperbolic tangent of @var{x}.
358 @end deftypefun
359
360 @comment math.h
361 @comment GNU
362 @deftypefun double asinh (double @var{x})
363 This function returns the inverse hyperbolic cosine of @var{x}.
364 @end deftypefun
365
366 @comment math.h
367 @comment GNU
368 @deftypefun double acosh (double @var{x})
369 This function returns the inverse hyperbolic cosine of @var{x}.  If
370 the argument is less than @code{1}, @code{acosh} returns @code{HUGE_VAL}.
371 @end deftypefun
372
373 @comment math.h
374 @comment GNU
375 @deftypefun double atanh (double @var{x})
376 This function returns the inverse hyperbolic cosine of @var{x}.  If
377 the absolute value of the argument is greater than or equal to @code{1},
378 @code{atanh} returns @code{HUGE_VAL}.
379 @end deftypefun
380
381
382 @node Normalization Functions
383 @section Normalization Functions
384
385 The functions described in this section are primarily provided as a way
386 to efficiently perform certain low-level manipulations on floating point
387 numbers that are represented internally using a binary radix;
388 @pxref{Floating-Point Representation}.  These functions are required to
389 have equivalent behavior even if the representation does not use a radix
390 of 2, but of course they are unlikely to be particularly efficient in
391 those cases.
392
393 @comment math.h
394 @comment GNU
395 @deftypefun double copysign (double @var{value}, double @var{sign})
396 The @code{copysign} function returns a value whose absolute value is the
397 same as that of @var{value}, and whose sign matches that of @var{sign}.
398 @end deftypefun
399
400 @comment math.h
401 @comment ANSI
402 @deftypefun double frexp (double @var{value}, int *@var{exponent})
403 The @code{frexp} function is used to normalize the number @var{value}.
404
405 If the argument @var{value} is not zero, the return value is a
406 floating-point number with magnitude in the range 1/2 (inclusive) to 1
407 (exclusive).  The corresponding exponent is stored in the location
408 pointed at by @var{exponent}; the return value multiplied by 2 raised to
409 this exponent is equal to the original number @var{value}.
410
411 If @var{value} is zero, then both parts of the result are zero.
412 @end deftypefun
413
414 @comment math.h
415 @comment ANSI
416 @deftypefun double ldexp (double @var{value}, int @var{exponent})
417 This function returns the result of multiplying the floating-point
418 number @var{value} by 2 raised to the power @var{exponent}.  (It can
419 be used to reassemble floating-point numbers that were taken apart
420 by @code{frexp}.)
421 @end deftypefun
422
423 @comment math.h
424 @comment GNU
425 @deftypefun double scalb (double @var{value}, int @var{exponent})
426 The @code{scalb} function does the same thing as @code{ldexp}.
427 @end deftypefun
428
429 @comment math.h
430 @comment GNU
431 @deftypefun double logb (double @var{x})
432 This function returns the base-2 exponent of @var{x}, an integer value
433 converted to a @code{double}.  The return value is such that dividing
434 the absolute value of @var{x} by @code{2} raised to this power is
435 greater than or equal to @code{1}, but less than @code{2}.
436
437 @strong{Incomplete:}  What happens if @var{x} is zero?
438 @end deftypefun
439
440
441 @node Rounding and Remainder Functions
442 @section Rounding and Remainder Functions
443
444 The functions listed here perform operations such as rounding, 
445 truncation, and remainder computation.
446
447 You can also convert floating-point numbers to integers simply by
448 casting them to @code{int}.  This discards the fractional part,
449 effectively rounding towards zero.  However, this only works if the
450 result can actually be represented as an @code{int} --- for very large
451 numbers, the result is undefined.  The functions listed here return the
452 result as a @code{double} instead to get around this problem.
453
454 @comment math.h
455 @comment ANSI
456 @deftypefun double ceil (double @var{x})
457 The @code{ceil} function rounds @var{x} upwards to the nearest integer,
458 returning that value as a @code{double}.
459 @end deftypefun
460
461 @comment math.h
462 @comment ANSI
463 @deftypefun double floor (double @var{x})
464 The @code{ceil} function rounds @var{x} downwards to the nearest
465 integer, returning that value as a @code{double}.
466 @end deftypefun
467
468 @comment math.h
469 @comment GNU
470 @deftypefun double rint (double @var{x})
471 This function returns the integer nearest @var{x} according to the
472 current rounding mode.  @xref{Floating-Point Parameters}, for information
473 about the @code{FLT_ROUNDS} macro.
474 @end deftypefun
475
476 @comment math.h
477 @comment ANSI
478 @deftypefun double modf (double @var{value}, double *@var{integer_part})
479 This function breaks the argument @var{value} into an integer part and a
480 fractional part.  Each of the parts has the same sign as the original
481 @var{value}, so the rounding of the integer part is towards zero.  The
482 integer part is stored at the location pointed at by @var{integer_part},
483 and the fractional part is returned.
484 @end deftypefun
485
486
487 @comment math.h
488 @comment ANSI
489 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
490 This function computes the remainder from dividing @var{numerator} by
491 @var{denominator}.  The result has the same sign as the @var{numerator}
492 and has magnitude less than the magnitude of the @var{denominator}.
493 (Recall that the built-in @samp{%} operator isn't defined on
494 floating-point values.)
495
496 The following @code{errno} error conditions are defined for this function:
497
498 @table @code
499 @item EDOM
500 The @var{denominator} is zero.
501 @end table
502 @end deftypefun
503
504 @comment math.h
505 @comment GNU
506 @deftypefun double drem (double @var{numerator}, double @var{denominator})
507 This function returns the remainder from dividing @var{numerator} by
508 @var{denominator}.  Specifically, the return value is @code{@var{numerator}
509 - @var{n} * @var{denominator}}, where @var{n} is the integer closest to
510 the exact quotient of @var{numerator} and @var{denominator}.  The absolute
511 value of the result is less than or equal to one half the absolute value
512 of the @var{denominator}.
513
514 The following @code{errno} error conditions are defined for this function:
515
516 @table @code
517 @item EDOM
518 The @var{denominator} is zero.
519 @end table
520 @end deftypefun
521
522
523 @node Pseudo-Random Numbers
524 @section Pseudo-Random Numbers
525
526 This section describes the GNU facilities for generating a series of
527 pseudo-random numbers.  The numbers generated are not necessarily truly
528 random; typically, the sequences repeat periodically, with the period
529 being a function of the number of bits in the @dfn{seed} or initial
530 state.
531 @cindex random numbers
532 @cindex pseudo-random numbers
533 @cindex seed (for random numbers)
534
535 There are actually two sets of random number functions provided.
536
537 @itemize @bullet
538 @item 
539 The @code{rand} and @code{srand} functions, described in @ref{ANSI C
540 Random Number Functions}, are part of the ANSI C standard.  You can use
541 these functions portably in many C implementations.
542
543 @item 
544 The @code{random} and @code{srandom} functions, described in @ref{BSD
545 Random Number Functions}, are derived from BSD Unix.  This uses a better
546 random number generator (producing numbers that are more random), but
547 is less portable.
548 @end itemize
549
550 For both sets of functions, you can get repeatable sequences of numbers
551 within a single implementation on a single machine type by specifying
552 the same initial seed value for the random number generator.  However,
553 the actual algorithm used to generate the random number series may be
554 implementation-dependent or implementation-dependent.
555
556
557 @menu
558 * ANSI C Random Number Functions::      @code{rand} and friends.
559 * BSD Random Number Functions::         @code{random} and friends.
560 @end menu
561
562 @node ANSI C Random Number Functions
563 @subsection ANSI C Random Number Functions
564
565 This section describes the random number functions that are part of
566 the ANSI C standard.  These functions represent the state of the
567 random number generator as an @code{int}.
568
569 To use these facilities, you should include the header file
570 @file{<stdlib.h>} in your program.
571
572 @comment stdlib.h
573 @comment ANSI
574 @defvr Macro RAND_MAX
575 The value of this macro is an integer constant expression that
576 represents the maximum possible value returned by the @code{rand}
577 function.  It is guaranteed to be at least @code{32767}.
578 @end defvr
579
580 @comment stdlib.h
581 @comment ANSI
582 @deftypefun int rand (void)
583 The @code{rand} function returns the next pseudo-random number in the
584 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
585 @end deftypefun
586
587 @comment stdlib.h
588 @comment ANSI
589 @deftypefun void srand (unsigned int @var{seed})
590 This function establishes @var{seed} as the seed for a new series of
591 pseudo-random numbers.  If @code{rand} is called before a seed has been
592 established with @code{srand}, it is equivalent to having specified an
593 initial seed value of @code{1}.
594 @end deftypefun
595
596 @node BSD Random Number Functions
597 @subsection BSD Random Number Functions
598
599 This section describes a set of random number generation functions
600 that are derived from BSD Unix.  The @code{random} function can generate
601 better random numbers than @code{rand}, because it maintains more bits
602 of internal state.
603
604 The prototypes for these functions are in @file{<stdlib.h>}.
605
606 @comment stdlib.h
607 @comment BSD
608 @deftypefun long int random (void)
609 This function returns the next pseudo-random number in the sequence.
610 The range of values returned is from @code{0} to @code{RAND_MAX}.
611 @end deftypefun
612
613 @comment stdlib.h
614 @comment BSD
615 @deftypefun void srandom (unsigned int @var{seed})
616 The @code{srandom} function sets the seed for the current random number
617 state to @var{seed}.  If you supply a @var{seed} value of @code{1}, this
618 will cause @code{random} to reproduce the default set of random numbers.
619 @end deftypefun
620
621 Because this random number generator uses more state information than
622 will fit in an @code{int}, @code{srandom} does not return a value that
623 is useful for saving and restoring the random number state.  Instead,
624 you should use the @code{initstate} and @code{setstate} functions to do
625 this.
626
627 @comment stdlib.h
628 @comment BSD
629 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
630 The @code{initstate} function is used to initialize the random number
631 generator state.  The @var{state} is an array of @var{size} bytes, used to
632 hold the state information.  The size must be at least 8 bytes, and optimal
633 sizes are 8, 16, 32, 64, 128, and 256.  The bigger the @var{state} array,
634 the better.
635
636 The return value is the previous value of the state information array.
637 @end deftypefun
638
639 @comment stdlib.h
640 @comment BSD
641 @deftypefun {void *} setstate (void *@var{state})
642 The @code{setstate} function restores the random number state
643 information @var{state}.  The argument must have been the result of
644 a previous call to @var{initstate} or @var{setstate}.  
645
646 The return value is the previous value of the state information array.
647 @end deftypefun
648
649
650
651
652
653 @node Integer Division
654 @section Integer Division
655
656 This section describes functions for performing integer division.
657 To use these facilities, you should include the header file
658 @file{<stdlib.h>} in your program.
659
660 These functions are not necessarily equivalent to the division performed
661 by the built-in @code{/} and @code{%} operators.  While the built-in
662 division operator is permitted to round in either direction if the
663 quotient is negative, the @code{div} and @code{ldiv} functions are
664 required to round towards zero.  It is also required that these
665 functions return a result @var{r} such that
666 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} be equal to
667 @var{numerator}.
668
669 @comment stdlib.h
670 @comment ANSI
671 @deftp {Data Type} div_t
672 This is a structure type used to hold the result returned by the @code{div}
673 function.  It has the following members:
674
675 @table @code
676 @item {int quot}
677 The quotient from the division.
678
679 @item {int rem}
680 The remainder from the division.
681 @end table
682 @end deftp
683
684 @comment stdlib.h
685 @comment ANSI
686 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
687 This function @code{div} computes the quotient and remainder from
688 the division of @var{numerator} by @var{denominator}, returning the
689 result in a structure of type @code{div_t}.
690
691 If the result cannot be represented (as in a division by zero), the
692 behavior is undefined.
693 @end deftypefun
694
695
696 @comment stdlib.h
697 @comment ANSI
698 @deftp {Data Type} ldiv_t
699 This is a structure type used to hold the result returned by the @code{ldiv}
700 function.  It has the following members:
701
702 @table @code
703 @item {long int quot}
704 The quotient from the division.
705
706 @item {long int rem}
707 The remainder from the division.
708 @end table
709
710 (This is identical to the type @code{div_t} except that the components
711 are of type @code{long int} rather than @code{int}.)
712 @end deftp
713
714 @comment stdlib.h
715 @comment ANSI
716 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
717 The @code{ldiv} function is similar to @code{div}, except that the
718 arguments are of type @code{long int} and the result is returned as a
719 structure of type @code{ldiv}.
720 @end deftypefun
721
722
723 @node Absolute Value
724 @section Absolute Value
725
726 These functions are provided for obtaining the absolute value of
727 integer values.  Prototypes for @code{abs} and @code{abs} are declared
728 in @file{<stdlib.h>}; @code{fabs} is declared in @file{<math.h>}.
729
730 @comment stdlib.h
731 @comment ANSI
732 @deftypefun int abs (int @var{number})
733 This function returns the absolute value (or magnitude) of @var{number}.
734 In a two's complement integer representation, the absolute value of
735 @code{INT_MIN} (the smallest possible @code{int}) cannot be represented;
736 in this case, the behavior of @code{abs} is undefined.
737 @end deftypefun
738
739 @comment stdlib.h
740 @comment ANSI
741 @deftypefun {long int} labs (long int @var{number})
742 This is similar to @code{abs}, except that both the argument and result
743 are of type @code{long int} rather than @code{int}.
744 @end deftypefun
745
746 @comment math.h
747 @comment ANSI
748 @deftypefun double fabs (double @var{number})
749 This function returns the absolute value of the floating-point number
750 @var{number}.
751 @end deftypefun
752
753 There is also the function @code{cabs} for computing the absolute value
754 of a complex number; @pxref{Exponentiation and Logarithms}.
755
756 @node Parsing of Numbers
757 @section Parsing of Numbers
758 @cindex parsing of numbers
759 @cindex string conversion
760 @cindex number syntax
761
762 This section describes functions for ``reading'' integer and
763 floating-point numbers from a string.  In many cases, it is more
764 appropriate to use @code{sscanf} or one of the related functions;
765 @pxref{Formatted Input}.  The syntax recognized by the formatted input
766 functions for the numeric conversions is exactly the same as the syntax
767 recognized by the functions described in this section.
768
769 These functions are declared in @file{<stdlib.h>}.
770
771 @menu
772 * Parsing of Integers::         Functions for conversion of integer values.
773 * Parsing of Floats::           Functions for conversion of floating-point
774                                  values.
775 @end menu
776
777 @node Parsing of Integers
778 @subsection Parsing of Integers
779 @cindex parsing of integers
780
781 @comment stdlib.h
782 @comment ANSI
783 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
784 The @code{strtol} (``string-to-long'') function converts the initial
785 part of @var{string} to a signed integer, which is returned as a value
786 of type @code{long int}.  
787
788 This function attempts to decompose @var{string} as follows:
789
790 @itemize @bullet
791 @item 
792 A (possibly empty) sequence of whitespace characters, as determined by
793 the @code{isspace} function (@pxref{Classification of Characters}).
794 These are discarded.
795
796 @item 
797 An optional plus or minus sign (@samp{+} or @samp{-}).
798
799 @item 
800 A nonempty sequence of digits in the radix specified by @var{base}.  If
801 @var{base} is zero, decimal radix is assumed unless the series of digits
802 begins with @samp{0} (specifying octal radix), or @samp{0x} or @samp{0X}
803 (specifying hexadecimal radix); in other words, the same syntax that is
804 used for integer constants in the C language is recognized.  Otherwise
805 @var{base} must have a value between @code{2} and @code{35}.  If
806 @var{base} is @code{16}, the digits may optionally be preceeded by
807 @samp{0x} or @samp{0X}.
808
809 @item 
810 Any remaining characters in the string.  If @var{tailptr} is not a null
811 pointer, a pointer to this tail of the string is stored in the object
812 it points to.
813 @end itemize
814
815 If the string is empty, contains only whitespace, or does not contain an
816 initial substring that has the expected syntax for an integer in the
817 specified @var{base}, no conversion is performed.  In this case,
818 @code{strtol} returns a value of zero and the value returned in
819 @var{tailptr} is the value of @var{string}.
820
821 In a locale other than the standard @code{"C"} locale, this function
822 may recognize additional implementation-dependent syntax.
823
824 If the string has valid syntax for an integer but the value is not
825 representable because of overflow, @code{strtol} returns either
826 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Integer Representation
827 Limits}), as appropriate for the sign of the value.
828
829 The following @code{errno} error conditions are defined for this
830 function:
831
832 @table @code
833 @item ERANGE
834 An overflow condition was detected.
835 @end table
836 @end deftypefun
837
838 @comment stdlib.h
839 @comment ANSI
840 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
841 The @code{strtoul} (``string-to-unsigned-long'') function is similar to
842 @code{strtol} except that it returns its value as an object of type
843 @code{unsigned long int}.  The value returned in case of overflow is
844 @code{ULONG_MAX} (@pxref{Integer Representation Limits}).
845 @end deftypefun
846
847 @comment stdlib.h
848 @comment ANSI
849 @deftypefun {long int} atol (const char *@var{string})
850 This function is similar to the @code{strtol} function with a @var{base}
851 argument of @code{10}, except that it need not detect overflow errors.
852 The @code{atol} function is provided mostly for compatibility with
853 existing code; using @code{strtol} is considered better style.
854 @end deftypefun
855
856 @comment stdlib.h
857 @comment ANSI
858 @deftypefun int atoi (const char *@var{string})
859 This function is similar to the @code{atol} function, except that
860 returns its value as an @code{int} rather than @code{long int}.  The
861 @code{atoi} function is also considered obsolete; use @code{strtol}
862 instead.
863 @end deftypefun
864
865 @node Predicates on Floats
866 @subsection Predicates on Floats
867
868 This section describes some miscellaneous test functions on doubles.
869 Prototypes for these functions appear in @file{<math.h>}.
870
871 @comment math.h
872 @comment GNU
873 @deftypefun int isinf (double @var{x})
874 This function returns @code{-1} if @var{x} represents negative infinity,
875 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
876 @end deftypefun
877
878 @comment math.h
879 @comment GNU
880 @deftypefun int isnan (double @var{x})
881 This function returns a nonzero value if @var{x} is the ``not a number''
882 value, and zero otherwise.
883 @end deftypefun
884
885 @comment math.h
886 @comment GNU
887 @deftypefun int finite (double @var{x})
888 This function returns a nonzero value if @var{x} is finite or the ``not
889 a number'' value, and zero otherwise.
890 @end deftypefun
891
892 @comment math.h
893 @comment GNU
894 @deftypefun double infnan (int @var{error})
895 @strong{Incomplete:}  I don't understand what this function does.
896 @end deftypefun
897
898
899
900 @strong{Portability Note:} The functions listed in this section are GNU
901 extensions.
902
903 @node Parsing of Floats
904 @subsection Parsing of Floats
905
906 @comment stdlib.h
907 @comment ANSI
908 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
909 The @code{strtod} (``string-to-double'') function converts the initial
910 part of @var{string} to a floating-point number, which is returned as a
911 value of type @code{double}.  
912
913 This function attempts to decompose @var{string} as follows:
914
915 @itemize @bullet
916 @item 
917 A (possibly empty) sequence of whitespace characters, as determined
918 by the @code{isspace} function.  These are discarded.
919
920 @item
921 An optional plus or minus sign (@samp{+} or @samp{-}).
922
923 @item
924 A nonempty sequence of digits optionally containing a decimal-point
925 character (@samp{.}).
926
927 @item
928 An optional exponent part, consisting of a character @samp{e} or
929 @samp{E}, an optional sign, and a sequence of digits.
930
931 @item
932 Any remaining characters in the string.  If @var{tailptr} is not a null
933 pointer, a pointer to this tail of the string is stored in the object it
934 points to.
935 @end itemize
936
937 If the string is empty, contains only whitespace, or does not contain
938 an initial substring that has the expected syntax for a floating-point
939 number, no conversion is performed.  In this case, @code{strtod} returns
940 a value of zero and the value returned in @var{tailptr} is the value of
941 @var{string}.
942
943 In a locale other than the standard @code{"C"} locale, this function
944 may recognize additional implementation-dependent syntax.
945
946 If the string has valid syntax for a floating-point number but the value
947 is not representable because of overflow, @code{strtod} returns either
948 positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
949 the sign of the value.  Similarly, if the value is not representable
950 because of underflow, @code{strtod} returns zero.
951
952 The following @code{errno} error conditions are defined for this
953 function:
954
955 @table @code
956 @item ERANGE
957 An overflow or underflow condition was detected.
958 @end table
959 @end deftypefun
960
961 @comment stdlib.h
962 @comment ANSI
963 @deftypefun double atof (const char *@var{string})
964 This function is similar to the @code{strtod} function, except that it
965 need not detect overflow and underflow errors.  The @code{atof} function
966 is provided mostly for compatibility with existing code; using
967 @code{strtod} is considered better style.
968 @end deftypefun
969