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