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