cadce992bb18f603a890b5800c716d121e83d144
[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 such that @code{quot*@var{denominator} + rem}
666 be equal to @var{numerator}.
667
668 @comment stdlib.h
669 @comment ANSI
670 @deftp {Data Type} div_t
671 This is a structure type used to hold the result returned by the @code{div}
672 function.  It has the following members:
673
674 @table @code
675 @item {int quot}
676 The quotient from the division.
677
678 @item {int rem}
679 The remainder from the division.
680 @end table
681 @end deftp
682
683 @comment stdlib.h
684 @comment ANSI
685 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
686 This function @code{div} computes the quotient and remainder from
687 the division of @var{numerator} by @var{denominator}, returning the
688 result in a structure of type @code{div_t}.
689
690 If the result cannot be represented (as in a division by zero), the
691 behavior is undefined.
692 @end deftypefun
693
694
695 @comment stdlib.h
696 @comment ANSI
697 @deftp {Data Type} ldiv_t
698 This is a structure type used to hold the result returned by the @code{ldiv}
699 function.  It has the following members:
700
701 @table @code
702 @item {long int quot}
703 The quotient from the division.
704
705 @item {long int rem}
706 The remainder from the division.
707 @end table
708
709 (This is identical to the type @code{div_t} except that the components
710 are of type @code{long int} rather than @code{int}.)
711 @end deftp
712
713 @comment stdlib.h
714 @comment ANSI
715 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
716 The @code{ldiv} function is similar to @code{div}, except that the
717 arguments are of type @code{long int} and the result is returned as a
718 structure of type @code{ldiv}.
719 @end deftypefun
720
721
722 @node Absolute Value
723 @section Absolute Value
724
725 These functions are provided for obtaining the absolute value of
726 integer values.  Prototypes for @code{abs} and @code{abs} are declared
727 in @file{<stdlib.h>}; @code{fabs} is declared in @file{<math.h>}.
728
729 @comment stdlib.h
730 @comment ANSI
731 @deftypefun int abs (int @var{number})
732 This function returns the absolute value (or magnitude) of @var{number}.
733 In a two's complement integer representation, the absolute value of
734 @code{INT_MIN} (the smallest possible @code{int}) cannot be represented;
735 in this case, the behavior of @code{abs} is undefined.
736 @end deftypefun
737
738 @comment stdlib.h
739 @comment ANSI
740 @deftypefun {long int} labs (long int @var{number})
741 This is similar to @code{abs}, except that both the argument and result
742 are of type @code{long int} rather than @code{int}.
743 @end deftypefun
744
745 @comment math.h
746 @comment ANSI
747 @deftypefun double fabs (double @var{number})
748 This function returns the absolute value of the floating-point number
749 @var{number}.
750 @end deftypefun
751
752 There is also the function @code{cabs} for computing the absolute value
753 of a complex number; @pxref{Exponentiation and Logarithms}.
754
755 @node Parsing of Numbers
756 @section Parsing of Numbers
757 @cindex parsing of numbers
758 @cindex string conversion
759 @cindex number syntax
760
761 This section describes functions for ``reading'' integer and
762 floating-point numbers from a string.  In many cases, it is more
763 appropriate to use @code{sscanf} or one of the related functions;
764 @pxref{Formatted Input}.  The syntax recognized by the formatted input
765 functions for the numeric conversions is exactly the same as the syntax
766 recognized by the functions described in this section.
767
768 These functions are declared in @file{<stdlib.h>}.
769
770 @menu
771 * Parsing of Integers::         Functions for conversion of integer values.
772 * Parsing of Floats::           Functions for conversion of floating-point
773                                  values.
774 @end menu
775
776 @node Parsing of Integers
777 @subsection Parsing of Integers
778 @cindex parsing of integers
779
780 @comment stdlib.h
781 @comment ANSI
782 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
783 The @code{strtol} (``string-to-long'') function converts the initial
784 part of @var{string} to a signed integer, which is returned as a value
785 of type @code{long int}.  
786
787 This function attempts to decompose @var{string} as follows:
788
789 @itemize @bullet
790 @item 
791 A (possibly empty) sequence of whitespace characters, as determined by
792 the @code{isspace} function (@pxref{Classification of Characters}).
793 These are discarded.
794
795 @item 
796 An optional plus or minus sign (@samp{+} or @samp{-}).
797
798 @item 
799 A nonempty sequence of digits in the radix specified by @var{base}.  If
800 @var{base} is zero, decimal radix is assumed unless the series of digits
801 begins with @samp{0} (specifying octal radix), or @samp{0x} or @samp{0X}
802 (specifying hexadecimal radix); in other words, the same syntax that is
803 used for integer constants in the C language is recognized.  Otherwise
804 @var{base} must have a value between @code{2} and @code{35}.  If
805 @var{base} is @code{16}, the digits may optionally be preceeded by
806 @samp{0x} or @samp{0X}.
807
808 @item 
809 Any remaining characters in the string.  If @var{tailptr} is not a null
810 pointer, a pointer to this tail of the string is stored in the object
811 it points to.
812 @end itemize
813
814 If the string is empty, contains only whitespace, or does not contain an
815 initial substring that has the expected syntax for an integer in the
816 specified @var{base}, no conversion is performed.  In this case,
817 @code{strtol} returns a value of zero and the value returned in
818 @var{tailptr} is the value of @var{string}.
819
820 In a locale other than the standard @code{"C"} locale, this function
821 may recognize additional implementation-dependent syntax.
822
823 If the string has valid syntax for an integer but the value is not
824 representable because of overflow, @code{strtol} returns either
825 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Integer Representation
826 Limits}), as appropriate for the sign of the value.
827
828 The following @code{errno} error conditions are defined for this
829 function:
830
831 @table @code
832 @item ERANGE
833 An overflow condition was detected.
834 @end table
835 @end deftypefun
836
837 @comment stdlib.h
838 @comment ANSI
839 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
840 The @code{strtoul} (``string-to-unsigned-long'') function is similar to
841 @code{strtol} except that it returns its value as an object of type
842 @code{unsigned long int}.  The value returned in case of overflow is
843 @code{ULONG_MAX} (@pxref{Integer Representation Limits}).
844 @end deftypefun
845
846 @comment stdlib.h
847 @comment ANSI
848 @deftypefun {long int} atol (const char *@var{string})
849 This function is similar to the @code{strtol} function with a @var{base}
850 argument of @code{10}, except that it need not detect overflow errors.
851 The @code{atol} function is provided mostly for compatibility with
852 existing code; using @code{strtol} is considered better style.
853 @end deftypefun
854
855 @comment stdlib.h
856 @comment ANSI
857 @deftypefun int atoi (const char *@var{string})
858 This function is similar to the @code{atol} function, except that
859 returns its value as an @code{int} rather than @code{long int}.  The
860 @code{atoi} function is also considered obsolete; use @code{strtol}
861 instead.
862 @end deftypefun
863
864 @node Predicates on Floats
865 @subsection Predicates on Floats
866
867 This section describes some miscellaneous test functions on doubles.
868 Prototypes for these functions appear in @file{<math.h>}.
869
870 @comment math.h
871 @comment GNU
872 @deftypefun int isinf (double @var{x})
873 This function returns @code{-1} if @var{x} represents negative infinity,
874 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
875 @end deftypefun
876
877 @comment math.h
878 @comment GNU
879 @deftypefun int isnan (double @var{x})
880 This function returns a nonzero value if @var{x} is the ``not a number''
881 value, and zero otherwise.
882 @end deftypefun
883
884 @comment math.h
885 @comment GNU
886 @deftypefun int finite (double @var{x})
887 This function returns a nonzero value if @var{x} is finite or the ``not
888 a number'' value, and zero otherwise.
889 @end deftypefun
890
891 @comment math.h
892 @comment GNU
893 @deftypefun double infnan (int @var{error})
894 @strong{Incomplete:}  I don't understand what this function does.
895 @end deftypefun
896
897
898
899 @strong{Portability Note:} The functions listed in this section are GNU
900 extensions.
901
902 @node Parsing of Floats
903 @subsection Parsing of Floats
904
905 @comment stdlib.h
906 @comment ANSI
907 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
908 The @code{strtod} (``string-to-double'') function converts the initial
909 part of @var{string} to a floating-point number, which is returned as a
910 value of type @code{double}.  
911
912 This function attempts to decompose @var{string} as follows:
913
914 @itemize @bullet
915 @item 
916 A (possibly empty) sequence of whitespace characters, as determined
917 by the @code{isspace} function.  These are discarded.
918
919 @item
920 An optional plus or minus sign (@samp{+} or @samp{-}).
921
922 @item
923 A nonempty sequence of digits optionally containing a decimal-point
924 character (@samp{.}).
925
926 @item
927 An optional exponent part, consisting of a character @samp{e} or
928 @samp{E}, an optional sign, and a sequence of digits.
929
930 @item
931 Any remaining characters in the string.  If @var{tailptr} is not a null
932 pointer, a pointer to this tail of the string is stored in the object it
933 points to.
934 @end itemize
935
936 If the string is empty, contains only whitespace, or does not contain
937 an initial substring that has the expected syntax for a floating-point
938 number, no conversion is performed.  In this case, @code{strtod} returns
939 a value of zero and the value returned in @var{tailptr} is the value of
940 @var{string}.
941
942 In a locale other than the standard @code{"C"} locale, this function
943 may recognize additional implementation-dependent syntax.
944
945 If the string has valid syntax for a floating-point number but the value
946 is not representable because of overflow, @code{strtod} returns either
947 positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
948 the sign of the value.  Similarly, if the value is not representable
949 because of underflow, @code{strtod} returns zero.
950
951 The following @code{errno} error conditions are defined for this
952 function:
953
954 @table @code
955 @item ERANGE
956 An overflow or underflow condition was detected.
957 @end table
958 @end deftypefun
959
960 @comment stdlib.h
961 @comment ANSI
962 @deftypefun double atof (const char *@var{string})
963 This function is similar to the @code{strtod} function, except that it
964 need not detect overflow and underflow errors.  The @code{atof} function
965 is provided mostly for compatibility with existing code; using
966 @code{strtod} is considered better style.
967 @end deftypefun
968