1 @node Mathematics
2 @chapter Mathematics
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
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}.
19 @strong{Incomplete:}  This chapter doesn't have any examples.
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
33 @node Domain and Range Errors
34 @section Domain and Range Errors
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}.
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.
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.
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}.
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.)
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.
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.
82 The value of this macro is used as the return value from various
83 mathematical functions in overflow situations.
84 @end deftypevr
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.
91 @node Trigonometric Functions
92 @section Trigonometric Functions
93 @cindex trignometric functions
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.
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:
103 @example
104 #define PI 3.14159265358979323846264338327
105 @end example
107 @noindent
108 You can also compute the value of pi with the expression @code{acos
109 (-1.0)}.
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
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
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.
132 The following @code{errno} error conditions are defined for this function:
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
144 @node Inverse Trigonometric Functions
145 @section Inverse Trigonometric Functions
146 @cindex inverse trigonmetric functions
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.
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).
160 The following @code{errno} error conditions are defined for this function:
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
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).
177 The following @code{errno} error conditions are defined for this function:
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
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
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.
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}.)
213 The following @code{errno} error conditions are defined for this function:
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
223 @node Exponentiation and Logarithms
224 @section Exponentiation and Logarithms
225 @cindex exponentiation functions
226 @cindex power functions
227 @cindex logarithm functions
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}.
235 The following @code{errno} error conditions are defined for this function:
237 @table @code
238 @item ERANGE
239 The magnitude of the result is too large to be representable.
240 @end table
241 @end deftypefun
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.
250 The following @code{errno} error conditions are defined for this function:
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}.
258 @item ERANGE
259 The result of the function on an argument of zero is not defined.
260 @end table
261 @end deftypefun
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
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}.
277 The following @code{errno} error conditions are defined for this function:
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.
284 @item ERANGE
285 An underflow or overflow condition was detected in the result.
286 @end table
287 @end deftypefun
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}.
295 The following @code{errno} error conditions are defined for this function:
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
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
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
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
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
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
345 @node Hyperbolic Functions
346 @section Hyperbolic Functions
347 @cindex hyperbolic functions
349 The functions in this section are related to the exponential functions;
350 see @ref{Exponentiation and Logarithms}.
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:
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
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:
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
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
389 @cindex inverse hyperbolic functions
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
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
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
415 @node Pseudo-Random Numbers
416 @section Pseudo-Random Numbers
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)
427 There are actually two sets of random number functions provided.
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.
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
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.
448 @menu
449 * ANSI C Random Number Functions::      @code{rand} and friends.
450 * BSD Random Number Functions::         @code{random} and friends.
451 @end menu
453 @node ANSI C Random Number Functions
454 @subsection ANSI C Random Number Functions
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}.
460 To use these facilities, you should include the header file
461 @file{stdlib.h} in your program.
462 @pindex stdlib.h
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
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
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.
488 To produce truly random numbers (not just pseudo-random), do @code{srand
489 (time (0))}.
490 @end deftypefun
492 @node BSD Random Number Functions
493 @subsection BSD Random Number Functions
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.
500 The prototypes for these functions are in @file{stdlib.h}.
501 @pindex stdlib.h
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
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.
518 To produce truly random numbers (not just pseudo-random), do
519 @code{srandom (time (0))}.
520 @end deftypefun
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.
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.
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
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}.
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
554 @node Absolute Value
555 @section Absolute Value
556 @cindex absolute value functions
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.
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
567 @comment stdlib.h
568 @comment ANSI
569 @deftypefun int abs (int @var{number})
570 This function returns the absolute value of @var{number}.
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
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
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
591 There is also the function @code{cabs} for computing the absolute value
592 of a complex number; see @ref{Exponentiation and Logarithms}.
594 @node Arithmetic
595 @chapter Low-Level Arithmetic Functions
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}.
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
613 @node Normalization Functions
614 @section Normalization Functions
615 @cindex normalization functions (floating-point)
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.
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
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}.
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}.
643 If @var{value} is zero, then both parts of the result are zero.
644 @end deftypefun
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
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
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}.
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).
673 @strong{Incomplete:}  What happens if @var{x} is zero?
674 @end deftypefun
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
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.
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.
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
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
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
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
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.
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.)
741 The following @code{errno} error conditions are defined for this function:
743 @table @code
744 @item EDOM
745 The @var{denominator} is zero.
746 @end table
747 @end deftypefun
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}.
759 The following @code{errno} error conditions are defined for this function:
761 @table @code
762 @item EDOM
763 The @var{denominator} is zero.
764 @end table
765 @end deftypefun
768 @node Integer Division
769 @section Integer Division
770 @cindex integer division functions
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.
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}.
782 To use these facilities, you should include the header file
783 @file{stdlib.h} in your program.
784 @pindex stdlib.h
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:
792 @table @code
793 @item {int quot}
794 The quotient from the division.
796 @item {int rem}
797 The remainder from the division.
798 @end table
799 @end deftp
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}.
808 If the result cannot be represented (as in a division by zero), the
809 behavior is undefined.
810 @end deftypefun
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:
819 @table @code
820 @item {long int quot}
821 The quotient from the division.
823 @item {long int rem}
824 The remainder from the division.
825 @end table
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
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
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
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.
854 These functions are declared in @file{stdlib.h}.
855 @pindex stdlib.h
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
863 @node Parsing of Integers
864 @subsection Parsing of Integers
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}.
873 This function attempts to decompose @var{string} as follows:
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.
881 @item
882 An optional plus or minus sign (@samp{+} or @samp{-}).
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}.
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
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}.
906 In a locale other than the standard @code{"C"} locale, this function
907 may recognize additional implementation-dependent syntax.
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.
914 The following @code{errno} error conditions are defined for this
915 function:
917 @table @code
918 @item ERANGE
919 An overflow condition was detected.
920 @end table
921 @end deftypefun
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
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
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
951 @node Parsing of Floats
952 @subsection Parsing of Floats
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}.
961 This function attempts to decompose @var{string} as follows:
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.
969 @item
970 An optional plus or minus sign (@samp{+} or @samp{-}).
972 @item
973 A nonempty sequence of digits optionally containing a decimal-point
974 character (@samp{.}).
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.
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
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}.
992 In a locale other than the standard @code{"C"} locale, this function may
993 recognize additional locale-dependent syntax.
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.
1001 The following @code{errno} error conditions are defined for this
1002 function:
1004 @table @code
1005 @item ERANGE
1006 An overflow or underflow condition was detected.
1007 @end table
1008 @end deftypefun
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
1019 @node Predicates on Floats
1020 @section Predicates on Floats
1021 @cindex predicates on floats
1023 This section describes some miscellaneous test functions on doubles.
1024 Prototypes for these functions appear in @file{math.h}.
1025 @pindex math.h
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
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
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
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
1054 @strong{Portability Note:} The functions listed in this section are GNU
1055 extensions.