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