1 @node Mathematics
2 @chapter Mathematics --- @file{<math.h>}
3 @pindex <math.h>
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>}.
10 @strong{Incomplete:}  This chapter doesn't have any examples.
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
32 @node Domain and Range Errors
33 @section Domain and Range Errors
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}.
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.
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}.
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.
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}.
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.)
82 The value of this macro is used as the return value from various
83 mathematical functions in overflow situations.
84 @end defvr
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.
91 @node Trigonometric Functions
92 @section Trigonometric Functions
94 @strong{Incomplete:}  What font convention should be used for things
95 like ``pi'' and ``e''?
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.
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:
105 @example
106 #define PI 3.14159265358979323846264338327
107 @end example
109 @noindent
110 You can also compute the value of pi with the expression @samp{acos (-1.0)}.
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
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
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.
132 The following @code{errno} error conditions are defined for this function:
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
144 @node Inverse Trigonometric Functions
145 @section Inverse Trigonometric Functions
147 These are the usual arc sine, arc cosine, and arc tangent functions.
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).
155 The following @code{errno} error conditions are defined for this function:
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
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).
170 The following @code{errno} error conditions are defined for this function:
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
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
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).
196 The following @code{errno} error conditions are defined for this function:
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
206 @node Exponentiation and Logarithms
207 @section Exponentiation and Logarithms
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}.
215 The following @code{errno} error conditions are defined for this function:
217 @table @code
218 @item ERANGE
219 The magnitude of the result is too large to be representable.
220 @end table
221 @end deftypefun
223 @comment math.h
224 @comment ANSI
225 @deftypefun double log (double @var{x})
226 This function returns the natural logarithm of @var{x}.
228 The following @code{errno} error conditions are defined for this function:
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}.
236 @item ERANGE
237 The result of the function on an argument of zero is not defined.
238 @end table
239 @end deftypefun
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
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}.
254 The following @code{errno} error conditions are defined for this function:
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.
261 @item ERANGE
262 An underflow or overflow condition was detected in the result.
263 @end table
264 @end deftypefun
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}.
271 The following @code{errno} error conditions are defined for this function:
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
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
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
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
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
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
322 @node Hyperbolic Functions
323 @section Hyperbolic Functions
325 The functions in this section are related to the exponential and
326 functions; @pxref{Exponentiation and Logarithms}.
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:
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
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:
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
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
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
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
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
382 @node Normalization Functions
383 @section Normalization Functions
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.
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
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}.
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}.
411 If @var{value} is zero, then both parts of the result are zero.
412 @end deftypefun
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
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
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}.
437 @strong{Incomplete:}  What happens if @var{x} is zero?
438 @end deftypefun
441 @node Rounding and Remainder Functions
442 @section Rounding and Remainder Functions
444 The functions listed here perform operations such as rounding,
445 truncation, and remainder computation.
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.
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
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
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
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
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.)
496 The following @code{errno} error conditions are defined for this function:
498 @table @code
499 @item EDOM
500 The @var{denominator} is zero.
501 @end table
502 @end deftypefun
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}.
514 The following @code{errno} error conditions are defined for this function:
516 @table @code
517 @item EDOM
518 The @var{denominator} is zero.
519 @end table
520 @end deftypefun
523 @node Pseudo-Random Numbers
524 @section Pseudo-Random Numbers
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)
535 There are actually two sets of random number functions provided.
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.
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
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.
557 @menu
558 * ANSI C Random Number Functions::      @code{rand} and friends.
559 * BSD Random Number Functions::         @code{random} and friends.
560 @end menu
562 @node ANSI C Random Number Functions
563 @subsection ANSI C Random Number Functions
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}.
569 To use these facilities, you should include the header file
570 @file{<stdlib.h>} in your program.
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
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
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
596 @node BSD Random Number Functions
597 @subsection BSD Random Number Functions
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.
604 The prototypes for these functions are in @file{<stdlib.h>}.
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
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
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.
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.
636 The return value is the previous value of the state information array.
637 @end deftypefun
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}.
646 The return value is the previous value of the state information array.
647 @end deftypefun
653 @node Integer Division
654 @section Integer Division
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.
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}.
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:
675 @table @code
676 @item {int quot}
677 The quotient from the division.
679 @item {int rem}
680 The remainder from the division.
681 @end table
682 @end deftp
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}.
691 If the result cannot be represented (as in a division by zero), the
692 behavior is undefined.
693 @end deftypefun
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:
702 @table @code
703 @item {long int quot}
704 The quotient from the division.
706 @item {long int rem}
707 The remainder from the division.
708 @end table
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
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
723 @node Absolute Value
724 @section Absolute Value
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>}.
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
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
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
753 There is also the function @code{cabs} for computing the absolute value
754 of a complex number; @pxref{Exponentiation and Logarithms}.
756 @node Parsing of Numbers
757 @section Parsing of Numbers
758 @cindex parsing of numbers
759 @cindex string conversion
760 @cindex number syntax
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.
769 These functions are declared in @file{<stdlib.h>}.
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
777 @node Parsing of Integers
778 @subsection Parsing of Integers
779 @cindex parsing of integers
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}.
788 This function attempts to decompose @var{string} as follows:
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.
796 @item
797 An optional plus or minus sign (@samp{+} or @samp{-}).
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}.
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
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}.
821 In a locale other than the standard @code{"C"} locale, this function
822 may recognize additional implementation-dependent syntax.
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.
829 The following @code{errno} error conditions are defined for this
830 function:
832 @table @code
833 @item ERANGE
834 An overflow condition was detected.
835 @end table
836 @end deftypefun
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
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
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
865 @node Predicates on Floats
866 @subsection Predicates on Floats
868 This section describes some miscellaneous test functions on doubles.
869 Prototypes for these functions appear in @file{<math.h>}.
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
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
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
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
900 @strong{Portability Note:} The functions listed in this section are GNU
901 extensions.
903 @node Parsing of Floats
904 @subsection Parsing of Floats
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}.
913 This function attempts to decompose @var{string} as follows:
915 @itemize @bullet
916 @item
917 A (possibly empty) sequence of whitespace characters, as determined
918 by the @code{isspace} function.  These are discarded.
920 @item
921 An optional plus or minus sign (@samp{+} or @samp{-}).
923 @item
924 A nonempty sequence of digits optionally containing a decimal-point
925 character (@samp{.}).
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.
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
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}.
943 In a locale other than the standard @code{"C"} locale, this function
944 may recognize additional implementation-dependent syntax.
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.
952 The following @code{errno} error conditions are defined for this
953 function:
955 @table @code
956 @item ERANGE
957 An overflow or underflow condition was detected.
958 @end table
959 @end deftypefun
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