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