Update.
[glibc.git] / manual / arith.texi
blobb95946a034abaeeb2971be1a110e617f3b5e42a8
1 @node Arithmetic, Date and Time, Mathematics, Top
2 @c %MENU% Low level arithmetic functions
3 @chapter Arithmetic Functions
5 This chapter contains information about functions for doing basic
6 arithmetic operations, such as splitting a float into its integer and
7 fractional parts or retrieving the imaginary part of a complex value.
8 These functions are declared in the header files @file{math.h} and
9 @file{complex.h}.
11 @menu
12 * Floating Point Numbers::      Basic concepts.  IEEE 754.
13 * Floating Point Classes::      The five kinds of floating-point number.
14 * Floating Point Errors::       When something goes wrong in a calculation.
15 * Rounding::                    Controlling how results are rounded.
16 * Control Functions::           Saving and restoring the FPU's state.
17 * Arithmetic Functions::        Fundamental operations provided by the library.
18 * Complex Numbers::             The types.  Writing complex constants.
19 * Operations on Complex::       Projection, conjugation, decomposition.
20 * Integer Division::            Integer division with guaranteed rounding.
21 * Parsing of Numbers::          Converting strings to numbers.
22 * System V Number Conversion::  An archaic way to convert numbers to strings.
23 @end menu
25 @node Floating Point Numbers
26 @section Floating Point Numbers
27 @cindex floating point
28 @cindex IEEE 754
29 @cindex IEEE floating point
31 Most computer hardware has support for two different kinds of numbers:
32 integers (@math{@dots{}-3, -2, -1, 0, 1, 2, 3@dots{}}) and
33 floating-point numbers.  Floating-point numbers have three parts: the
34 @dfn{mantissa}, the @dfn{exponent}, and the @dfn{sign bit}.  The real
35 number represented by a floating-point value is given by
36 @tex
37 $(s \mathrel? -1 \mathrel: 1) \cdot 2^e \cdot M$
38 @end tex
39 @ifnottex
40 @math{(s ? -1 : 1) @mul{} 2^e @mul{} M}
41 @end ifnottex
42 where @math{s} is the sign bit, @math{e} the exponent, and @math{M}
43 the mantissa.  @xref{Floating Point Concepts}, for details.  (It is
44 possible to have a different @dfn{base} for the exponent, but all modern
45 hardware uses @math{2}.)
47 Floating-point numbers can represent a finite subset of the real
48 numbers.  While this subset is large enough for most purposes, it is
49 important to remember that the only reals that can be represented
50 exactly are rational numbers that have a terminating binary expansion
51 shorter than the width of the mantissa.  Even simple fractions such as
52 @math{1/5} can only be approximated by floating point.
54 Mathematical operations and functions frequently need to produce values
55 that are not representable.  Often these values can be approximated
56 closely enough for practical purposes, but sometimes they can't.
57 Historically there was no way to tell when the results of a calculation
58 were inaccurate.  Modern computers implement the @w{IEEE 754} standard
59 for numerical computations, which defines a framework for indicating to
60 the program when the results of calculation are not trustworthy.  This
61 framework consists of a set of @dfn{exceptions} that indicate why a
62 result could not be represented, and the special values @dfn{infinity}
63 and @dfn{not a number} (NaN).
65 @node Floating Point Classes
66 @section Floating-Point Number Classification Functions
67 @cindex floating-point classes
68 @cindex classes, floating-point
69 @pindex math.h
71 @w{ISO C 9x} defines macros that let you determine what sort of
72 floating-point number a variable holds.
74 @comment math.h
75 @comment ISO
76 @deftypefn {Macro} int fpclassify (@emph{float-type} @var{x})
77 This is a generic macro which works on all floating-point types and
78 which returns a value of type @code{int}.  The possible values are:
80 @vtable @code
81 @item FP_NAN
82 The floating-point number @var{x} is ``Not a Number'' (@pxref{Infinity
83 and NaN})
84 @item FP_INFINITE
85 The value of @var{x} is either plus or minus infinity (@pxref{Infinity
86 and NaN})
87 @item FP_ZERO
88 The value of @var{x} is zero.  In floating-point formats like @w{IEEE
89 754}, where zero can be signed, this value is also returned if
90 @var{x} is negative zero.
91 @item FP_SUBNORMAL
92 Numbers whose absolute value is too small to be represented in the
93 normal format are represented in an alternate, @dfn{denormalized} format
94 (@pxref{Floating Point Concepts}).  This format is less precise but can
95 represent values closer to zero.  @code{fpclassify} returns this value
96 for values of @var{x} in this alternate format.
97 @item FP_NORMAL
98 This value is returned for all other values of @var{x}.  It indicates
99 that there is nothing special about the number.
100 @end vtable
102 @end deftypefn
104 @code{fpclassify} is most useful if more than one property of a number
105 must be tested.  There are more specific macros which only test one
106 property at a time.  Generally these macros execute faster than
107 @code{fpclassify}, since there is special hardware support for them.
108 You should therefore use the specific macros whenever possible.
110 @comment math.h
111 @comment ISO
112 @deftypefn {Macro} int isfinite (@emph{float-type} @var{x})
113 This macro returns a nonzero value if @var{x} is finite: not plus or
114 minus infinity, and not NaN.  It is equivalent to
116 @smallexample
117 (fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)
118 @end smallexample
120 @code{isfinite} is implemented as a macro which accepts any
121 floating-point type.
122 @end deftypefn
124 @comment math.h
125 @comment ISO
126 @deftypefn {Macro} int isnormal (@emph{float-type} @var{x})
127 This macro returns a nonzero value if @var{x} is finite and normalized.
128 It is equivalent to
130 @smallexample
131 (fpclassify (x) == FP_NORMAL)
132 @end smallexample
133 @end deftypefn
135 @comment math.h
136 @comment ISO
137 @deftypefn {Macro} int isnan (@emph{float-type} @var{x})
138 This macro returns a nonzero value if @var{x} is NaN.  It is equivalent
141 @smallexample
142 (fpclassify (x) == FP_NAN)
143 @end smallexample
144 @end deftypefn
146 Another set of floating-point classification functions was provided by
147 BSD.  The GNU C library also supports these functions; however, we
148 recommend that you use the C9x macros in new code.  Those are standard
149 and will be available more widely.  Also, since they are macros, you do
150 not have to worry about the type of their argument.
152 @comment math.h
153 @comment BSD
154 @deftypefun int isinf (double @var{x})
155 @comment math.h
156 @comment BSD
157 @deftypefunx int isinff (float @var{x})
158 @comment math.h
159 @comment BSD
160 @deftypefunx int isinfl (long double @var{x})
161 This function returns @code{-1} if @var{x} represents negative infinity,
162 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
163 @end deftypefun
165 @comment math.h
166 @comment BSD
167 @deftypefun int isnan (double @var{x})
168 @comment math.h
169 @comment BSD
170 @deftypefunx int isnanf (float @var{x})
171 @comment math.h
172 @comment BSD
173 @deftypefunx int isnanl (long double @var{x})
174 This function returns a nonzero value if @var{x} is a ``not a number''
175 value, and zero otherwise.
177 @strong{Note:} The @code{isnan} macro defined by @w{ISO C 9x} overrides
178 the BSD function.  This is normally not a problem, because the two
179 routines behave identically.  However, if you really need to get the BSD
180 function for some reason, you can write
182 @smallexample
183 (isnan) (x)
184 @end smallexample
185 @end deftypefun
187 @comment math.h
188 @comment BSD
189 @deftypefun int finite (double @var{x})
190 @comment math.h
191 @comment BSD
192 @deftypefunx int finitef (float @var{x})
193 @comment math.h
194 @comment BSD
195 @deftypefunx int finitel (long double @var{x})
196 This function returns a nonzero value if @var{x} is finite or a ``not a
197 number'' value, and zero otherwise.
198 @end deftypefun
200 @comment math.h
201 @comment BSD
202 @deftypefun double infnan (int @var{error})
203 This function is provided for compatibility with BSD.  Its argument is
204 an error code, @code{EDOM} or @code{ERANGE}; @code{infnan} returns the
205 value that a math function would return if it set @code{errno} to that
206 value.  @xref{Math Error Reporting}.  @code{-ERANGE} is also acceptable
207 as an argument, and corresponds to @code{-HUGE_VAL} as a value.
209 In the BSD library, on certain machines, @code{infnan} raises a fatal
210 signal in all cases.  The GNU library does not do likewise, because that
211 does not fit the @w{ISO C} specification.
212 @end deftypefun
214 @strong{Portability Note:} The functions listed in this section are BSD
215 extensions.
218 @node Floating Point Errors
219 @section Errors in Floating-Point Calculations
221 @menu
222 * FP Exceptions::               IEEE 754 math exceptions and how to detect them.
223 * Infinity and NaN::            Special values returned by calculations.
224 * Status bit operations::       Checking for exceptions after the fact.
225 * Math Error Reporting::        How the math functions report errors.
226 @end menu
228 @node FP Exceptions
229 @subsection FP Exceptions
230 @cindex exception
231 @cindex signal
232 @cindex zero divide
233 @cindex division by zero
234 @cindex inexact exception
235 @cindex invalid exception
236 @cindex overflow exception
237 @cindex underflow exception
239 The @w{IEEE 754} standard defines five @dfn{exceptions} that can occur
240 during a calculation.  Each corresponds to a particular sort of error,
241 such as overflow.
243 When exceptions occur (when exceptions are @dfn{raised}, in the language
244 of the standard), one of two things can happen.  By default the
245 exception is simply noted in the floating-point @dfn{status word}, and
246 the program continues as if nothing had happened.  The operation
247 produces a default value, which depends on the exception (see the table
248 below).  Your program can check the status word to find out which
249 exceptions happened.
251 Alternatively, you can enable @dfn{traps} for exceptions.  In that case,
252 when an exception is raised, your program will receive the @code{SIGFPE}
253 signal.  The default action for this signal is to terminate the
254 program.  @xref{Signal Handling}, for how you can change the effect of
255 the signal.
257 @findex matherr
258 In the System V math library, the user-defined function @code{matherr}
259 is called when certain exceptions occur inside math library functions.
260 However, the Unix98 standard deprecates this interface.  We support it
261 for historical compatibility, but recommend that you do not use it in
262 new programs.
264 @noindent
265 The exceptions defined in @w{IEEE 754} are:
267 @table @samp
268 @item Invalid Operation
269 This exception is raised if the given operands are invalid for the
270 operation to be performed.  Examples are
271 (see @w{IEEE 754}, @w{section 7}):
272 @enumerate
273 @item
274 Addition or subtraction: @math{@infinity{} - @infinity{}}.  (But
275 @math{@infinity{} + @infinity{} = @infinity{}}).
276 @item
277 Multiplication: @math{0 @mul{} @infinity{}}.
278 @item
279 Division: @math{0/0} or @math{@infinity{}/@infinity{}}.
280 @item
281 Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is
282 infinite.
283 @item
284 Square root if the operand is less then zero.  More generally, any
285 mathematical function evaluated outside its domain produces this
286 exception.
287 @item
288 Conversion of a floating-point number to an integer or decimal
289 string, when the number cannot be represented in the target format (due
290 to overflow, infinity, or NaN).
291 @item
292 Conversion of an unrecognizable input string.
293 @item
294 Comparison via predicates involving @math{<} or @math{>}, when one or
295 other of the operands is NaN.  You can prevent this exception by using
296 the unordered comparison functions instead; see @ref{FP Comparison Functions}.
297 @end enumerate
299 If the exception does not trap, the result of the operation is NaN.
301 @item Division by Zero
302 This exception is raised when a finite nonzero number is divided
303 by zero.  If no trap occurs the result is either @math{+@infinity{}} or
304 @math{-@infinity{}}, depending on the signs of the operands.
306 @item Overflow
307 This exception is raised whenever the result cannot be represented
308 as a finite value in the precision format of the destination.  If no trap
309 occurs the result depends on the sign of the intermediate result and the
310 current rounding mode (@w{IEEE 754}, @w{section 7.3}):
311 @enumerate
312 @item
313 Round to nearest carries all overflows to @math{@infinity{}}
314 with the sign of the intermediate result.
315 @item
316 Round toward @math{0} carries all overflows to the largest representable
317 finite number with the sign of the intermediate result.
318 @item
319 Round toward @math{-@infinity{}} carries positive overflows to the
320 largest representable finite number and negative overflows to
321 @math{-@infinity{}}.
323 @item
324 Round toward @math{@infinity{}} carries negative overflows to the
325 most negative representable finite number and positive overflows
326 to @math{@infinity{}}.
327 @end enumerate
329 Whenever the overflow exception is raised, the inexact exception is also
330 raised.
332 @item Underflow
333 The underflow exception is raised when an intermediate result is too
334 small to be calculated accurately, or if the operation's result rounded
335 to the destination precision is too small to be normalized.
337 When no trap is installed for the underflow exception, underflow is
338 signaled (via the underflow flag) only when both tininess and loss of
339 accuracy have been detected.  If no trap handler is installed the
340 operation continues with an imprecise small value, or zero if the
341 destination precision cannot hold the small exact result.
343 @item Inexact
344 This exception is signalled if a rounded result is not exact (such as
345 when calculating the square root of two) or a result overflows without
346 an overflow trap.
347 @end table
349 @node Infinity and NaN
350 @subsection Infinity and NaN
351 @cindex infinity
352 @cindex not a number
353 @cindex NaN
355 @w{IEEE 754} floating point numbers can represent positive or negative
356 infinity, and @dfn{NaN} (not a number).  These three values arise from
357 calculations whose result is undefined or cannot be represented
358 accurately.  You can also deliberately set a floating-point variable to
359 any of them, which is sometimes useful.  Some examples of calculations
360 that produce infinity or NaN:
362 @ifnottex
363 @smallexample
364 @math{1/0 = @infinity{}}
365 @math{log (0) = -@infinity{}}
366 @math{sqrt (-1) = NaN}
367 @end smallexample
368 @end ifnottex
369 @tex
370 $${1\over0} = \infty$$
371 $$\log 0 = -\infty$$
372 $$\sqrt{-1} = \hbox{NaN}$$
373 @end tex
375 When a calculation produces any of these values, an exception also
376 occurs; see @ref{FP Exceptions}.
378 The basic operations and math functions all accept infinity and NaN and
379 produce sensible output.  Infinities propagate through calculations as
380 one would expect: for example, @math{2 + @infinity{} = @infinity{}},
381 @math{4/@infinity{} = 0}, atan @math{(@infinity{}) = @pi{}/2}.  NaN, on
382 the other hand, infects any calculation that involves it.  Unless the
383 calculation would produce the same result no matter what real value
384 replaced NaN, the result is NaN.
386 In comparison operations, positive infinity is larger than all values
387 except itself and NaN, and negative infinity is smaller than all values
388 except itself and NaN.  NaN is @dfn{unordered}: it is not equal to,
389 greater than, or less than anything, @emph{including itself}. @code{x ==
390 x} is false if the value of @code{x} is NaN.  You can use this to test
391 whether a value is NaN or not, but the recommended way to test for NaN
392 is with the @code{isnan} function (@pxref{Floating Point Classes}).  In
393 addition, @code{<}, @code{>}, @code{<=}, and @code{>=} will raise an
394 exception when applied to NaNs.
396 @file{math.h} defines macros that allow you to explicitly set a variable
397 to infinity or NaN.
399 @comment math.h
400 @comment ISO
401 @deftypevr Macro float INFINITY
402 An expression representing positive infinity.  It is equal to the value
403 produced  by mathematical operations like @code{1.0 / 0.0}.
404 @code{-INFINITY} represents negative infinity.
406 You can test whether a floating-point value is infinite by comparing it
407 to this macro.  However, this is not recommended; you should use the
408 @code{isfinite} macro instead.  @xref{Floating Point Classes}.
410 This macro was introduced in the @w{ISO C 9X} standard.
411 @end deftypevr
413 @comment math.h
414 @comment GNU
415 @deftypevr Macro float NAN
416 An expression representing a value which is ``not a number''.  This
417 macro is a GNU extension, available only on machines that support the
418 ``not a number'' value---that is to say, on all machines that support
419 IEEE floating point.
421 You can use @samp{#ifdef NAN} to test whether the machine supports
422 NaN.  (Of course, you must arrange for GNU extensions to be visible,
423 such as by defining @code{_GNU_SOURCE}, and then you must include
424 @file{math.h}.)
425 @end deftypevr
427 @w{IEEE 754} also allows for another unusual value: negative zero.  This
428 value is produced when you divide a positive number by negative
429 infinity, or when a negative result is smaller than the limits of
430 representation.  Negative zero behaves identically to zero in all
431 calculations, unless you explicitly test the sign bit with
432 @code{signbit} or @code{copysign}.
434 @node Status bit operations
435 @subsection Examining the FPU status word
437 @w{ISO C 9x} defines functions to query and manipulate the
438 floating-point status word.  You can use these functions to check for
439 untrapped exceptions when it's convenient, rather than worrying about
440 them in the middle of a calculation.
442 These constants represent the various @w{IEEE 754} exceptions.  Not all
443 FPUs report all the different exceptions.  Each constant is defined if
444 and only if the FPU you are compiling for supports that exception, so
445 you can test for FPU support with @samp{#ifdef}.  They are defined in
446 @file{fenv.h}.
448 @vtable @code
449 @comment fenv.h
450 @comment ISO
451 @item FE_INEXACT
452  The inexact exception.
453 @comment fenv.h
454 @comment ISO
455 @item FE_DIVBYZERO
456  The divide by zero exception.
457 @comment fenv.h
458 @comment ISO
459 @item FE_UNDERFLOW
460  The underflow exception.
461 @comment fenv.h
462 @comment ISO
463 @item FE_OVERFLOW
464  The overflow exception.
465 @comment fenv.h
466 @comment ISO
467 @item FE_INVALID
468  The invalid exception.
469 @end vtable
471 The macro @code{FE_ALL_EXCEPT} is the bitwise OR of all exception macros
472 which are supported by the FP implementation.
474 These functions allow you to clear exception flags, test for exceptions,
475 and save and restore the set of exceptions flagged.
477 @comment fenv.h
478 @comment ISO
479 @deftypefun void feclearexcept (int @var{excepts})
480 This function clears all of the supported exception flags indicated by
481 @var{excepts}.
482 @end deftypefun
484 @comment fenv.h
485 @comment ISO
486 @deftypefun int fetestexcept (int @var{excepts})
487 Test whether the exception flags indicated by the parameter @var{except}
488 are currently set.  If any of them are, a nonzero value is returned
489 which specifies which exceptions are set.  Otherwise the result is zero.
490 @end deftypefun
492 To understand these functions, imagine that the status word is an
493 integer variable named @var{status}.  @code{feclearexcept} is then
494 equivalent to @samp{status &= ~excepts} and @code{fetestexcept} is
495 equivalent to @samp{(status & excepts)}.  The actual implementation may
496 be very different, of course.
498 Exception flags are only cleared when the program explicitly requests it,
499 by calling @code{feclearexcept}.  If you want to check for exceptions
500 from a set of calculations, you should clear all the flags first.  Here
501 is a simple example of the way to use @code{fetestexcept}:
503 @smallexample
505   double f;
506   int raised;
507   feclearexcept (FE_ALL_EXCEPT);
508   f = compute ();
509   raised = fetestexcept (FE_OVERFLOW | FE_INVALID);
510   if (raised & FE_OVERFLOW) @{ /* ... */ @}
511   if (raised & FE_INVALID) @{ /* ... */ @}
512   /* ... */
514 @end smallexample
516 You cannot explicitly set bits in the status word.  You can, however,
517 save the entire status word and restore it later.  This is done with the
518 following functions:
520 @comment fenv.h
521 @comment ISO
522 @deftypefun void fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts})
523 This function stores in the variable pointed to by @var{flagp} an
524 implementation-defined value representing the current setting of the
525 exception flags indicated by @var{excepts}.
526 @end deftypefun
528 @comment fenv.h
529 @comment ISO
530 @deftypefun void fesetexceptflag (const fexcept_t *@var{flagp}, int
531 @var{excepts})
532 This function restores the flags for the exceptions indicated by
533 @var{excepts} to the values stored in the variable pointed to by
534 @var{flagp}.
535 @end deftypefun
537 Note that the value stored in @code{fexcept_t} bears no resemblance to
538 the bit mask returned by @code{fetestexcept}.  The type may not even be
539 an integer.  Do not attempt to modify an @code{fexcept_t} variable.
541 @node Math Error Reporting
542 @subsection Error Reporting by Mathematical Functions
543 @cindex errors, mathematical
544 @cindex domain error
545 @cindex range error
547 Many of the math functions are defined only over a subset of the real or
548 complex numbers.  Even if they are mathematically defined, their result
549 may be larger or smaller than the range representable by their return
550 type.  These are known as @dfn{domain errors}, @dfn{overflows}, and
551 @dfn{underflows}, respectively.  Math functions do several things when
552 one of these errors occurs.  In this manual we will refer to the
553 complete response as @dfn{signalling} a domain error, overflow, or
554 underflow.
556 When a math function suffers a domain error, it raises the invalid
557 exception and returns NaN.  It also sets @var{errno} to @code{EDOM};
558 this is for compatibility with old systems that do not support @w{IEEE
559 754} exception handling.  Likewise, when overflow occurs, math
560 functions raise the overflow exception and return @math{@infinity{}} or
561 @math{-@infinity{}} as appropriate.  They also set @var{errno} to
562 @code{ERANGE}.  When underflow occurs, the underflow exception is
563 raised, and zero (appropriately signed) is returned.  @var{errno} may be
564 set to @code{ERANGE}, but this is not guaranteed.
566 Some of the math functions are defined mathematically to result in a
567 complex value over parts of their domains.  The most familiar example of
568 this is taking the square root of a negative number.  The complex math
569 functions, such as @code{csqrt}, will return the appropriate complex value
570 in this case.  The real-valued functions, such as @code{sqrt}, will
571 signal a domain error.
573 Some older hardware does not support infinities.  On that hardware,
574 overflows instead return a particular very large number (usually the
575 largest representable number).  @file{math.h} defines macros you can use
576 to test for overflow on both old and new hardware.
578 @comment math.h
579 @comment ISO
580 @deftypevr Macro double HUGE_VAL
581 @comment math.h
582 @comment ISO
583 @deftypevrx Macro float HUGE_VALF
584 @comment math.h
585 @comment ISO
586 @deftypevrx Macro {long double} HUGE_VALL
587 An expression representing a particular very large number.  On machines
588 that use @w{IEEE 754} floating point format, @code{HUGE_VAL} is infinity.
589 On other machines, it's typically the largest positive number that can
590 be represented.
592 Mathematical functions return the appropriately typed version of
593 @code{HUGE_VAL} or @code{@minus{}HUGE_VAL} when the result is too large
594 to be represented.
595 @end deftypevr
597 @node Rounding
598 @section Rounding Modes
600 Floating-point calculations are carried out internally with extra
601 precision, and then rounded to fit into the destination type.  This
602 ensures that results are as precise as the input data.  @w{IEEE 754}
603 defines four possible rounding modes:
605 @table @asis
606 @item Round to nearest.
607 This is the default mode.  It should be used unless there is a specific
608 need for one of the others.  In this mode results are rounded to the
609 nearest representable value.  If the result is midway between two
610 representable values, the even representable is chosen. @dfn{Even} here
611 means the lowest-order bit is zero.  This rounding mode prevents
612 statistical bias and guarantees numeric stability: round-off errors in a
613 lengthy calculation will remain smaller than half of @code{FLT_EPSILON}.
615 @c @item Round toward @math{+@infinity{}}
616 @item Round toward plus Infinity.
617 All results are rounded to the smallest representable value
618 which is greater than the result.
620 @c @item Round toward @math{-@infinity{}}
621 @item Round toward minus Infinity.
622 All results are rounded to the largest representable value which is less
623 than the result.
625 @item Round toward zero.
626 All results are rounded to the largest representable value whose
627 magnitude is less than that of the result.  In other words, if the
628 result is negative it is rounded up; if it is positive, it is rounded
629 down.
630 @end table
632 @noindent
633 @file{fenv.h} defines constants which you can use to refer to the
634 various rounding modes.  Each one will be defined if and only if the FPU
635 supports the corresponding rounding mode.
637 @table @code
638 @comment fenv.h
639 @comment ISO
640 @vindex FE_TONEAREST
641 @item FE_TONEAREST
642 Round to nearest.
644 @comment fenv.h
645 @comment ISO
646 @vindex FE_UPWARD
647 @item FE_UPWARD
648 Round toward @math{+@infinity{}}.
650 @comment fenv.h
651 @comment ISO
652 @vindex FE_DOWNWARD
653 @item FE_DOWNWARD
654 Round toward @math{-@infinity{}}.
656 @comment fenv.h
657 @comment ISO
658 @vindex FE_TOWARDZERO
659 @item FE_TOWARDZERO
660 Round toward zero.
661 @end table
663 Underflow is an unusual case.  Normally, @w{IEEE 754} floating point
664 numbers are always normalized (@pxref{Floating Point Concepts}).
665 Numbers smaller than @math{2^r} (where @math{r} is the minimum exponent,
666 @code{FLT_MIN_RADIX-1} for @var{float}) cannot be represented as
667 normalized numbers.  Rounding all such numbers to zero or @math{2^r}
668 would cause some algorithms to fail at 0.  Therefore, they are left in
669 denormalized form.  That produces loss of precision, since some bits of
670 the mantissa are stolen to indicate the decimal point.
672 If a result is too small to be represented as a denormalized number, it
673 is rounded to zero.  However, the sign of the result is preserved; if
674 the calculation was negative, the result is @dfn{negative zero}.
675 Negative zero can also result from some operations on infinity, such as
676 @math{4/-@infinity{}}.  Negative zero behaves identically to zero except
677 when the @code{copysign} or @code{signbit} functions are used to check
678 the sign bit directly.
680 At any time one of the above four rounding modes is selected.  You can
681 find out which one with this function:
683 @comment fenv.h
684 @comment ISO
685 @deftypefun int fegetround (void)
686 Returns the currently selected rounding mode, represented by one of the
687 values of the defined rounding mode macros.
688 @end deftypefun
690 @noindent
691 To change the rounding mode, use this function:
693 @comment fenv.h
694 @comment ISO
695 @deftypefun int fesetround (int @var{round})
696 Changes the currently selected rounding mode to @var{round}.  If
697 @var{round} does not correspond to one of the supported rounding modes
698 nothing is changed.  @code{fesetround} returns a nonzero value if it
699 changed the rounding mode, zero if the mode is not supported.
700 @end deftypefun
702 You should avoid changing the rounding mode if possible.  It can be an
703 expensive operation; also, some hardware requires you to compile your
704 program differently for it to work.  The resulting code may run slower.
705 See your compiler documentation for details.
706 @c This section used to claim that functions existed to round one number
707 @c in a specific fashion.  I can't find any functions in the library
708 @c that do that. -zw
710 @node Control Functions
711 @section Floating-Point Control Functions
713 @w{IEEE 754} floating-point implementations allow the programmer to
714 decide whether traps will occur for each of the exceptions, by setting
715 bits in the @dfn{control word}.  In C, traps result in the program
716 receiving the @code{SIGFPE} signal; see @ref{Signal Handling}.
718 @strong{Note:} @w{IEEE 754} says that trap handlers are given details of
719 the exceptional situation, and can set the result value.  C signals do
720 not provide any mechanism to pass this information back and forth.
721 Trapping exceptions in C is therefore not very useful.
723 It is sometimes necessary to save the state of the floating-point unit
724 while you perform some calculation.  The library provides functions
725 which save and restore the exception flags, the set of exceptions that
726 generate traps, and the rounding mode.  This information is known as the
727 @dfn{floating-point environment}.
729 The functions to save and restore the floating-point environment all use
730 a variable of type @code{fenv_t} to store information.  This type is
731 defined in @file{fenv.h}.  Its size and contents are
732 implementation-defined.  You should not attempt to manipulate a variable
733 of this type directly.
735 To save the state of the FPU, use one of these functions:
737 @comment fenv.h
738 @comment ISO
739 @deftypefun void fegetenv (fenv_t *@var{envp})
740 Store the floating-point environment in the variable pointed to by
741 @var{envp}.
742 @end deftypefun
744 @comment fenv.h
745 @comment ISO
746 @deftypefun int feholdexcept (fenv_t *@var{envp})
747 Store the current floating-point environment in the object pointed to by
748 @var{envp}.  Then clear all exception flags, and set the FPU to trap no
749 exceptions.  Not all FPUs support trapping no exceptions; if
750 @code{feholdexcept} cannot set this mode, it returns zero.  If it
751 succeeds, it returns a nonzero value.
752 @end deftypefun
754 The functions which restore the floating-point environment can take two
755 kinds of arguments:
757 @itemize @bullet
758 @item
759 Pointers to @code{fenv_t} objects, which were initialized previously by a
760 call to @code{fegetenv} or @code{feholdexcept}.
761 @item
762 @vindex FE_DFL_ENV
763 The special macro @code{FE_DFL_ENV} which represents the floating-point
764 environment as it was available at program start.
765 @item
766 Implementation defined macros with names starting with @code{FE_}.
768 @vindex FE_NOMASK_ENV
769 If possible, the GNU C Library defines a macro @code{FE_NOMASK_ENV}
770 which represents an environment where every exception raised causes a
771 trap to occur.  You can test for this macro using @code{#ifdef}.  It is
772 only defined if @code{_GNU_SOURCE} is defined.
774 Some platforms might define other predefined environments.
775 @end itemize
777 @noindent
778 To set the floating-point environment, you can use either of these
779 functions:
781 @comment fenv.h
782 @comment ISO
783 @deftypefun void fesetenv (const fenv_t *@var{envp})
784 Set the floating-point environment to that described by @var{envp}.
785 @end deftypefun
787 @comment fenv.h
788 @comment ISO
789 @deftypefun void feupdateenv (const fenv_t *@var{envp})
790 Like @code{fesetenv}, this function sets the floating-point environment
791 to that described by @var{envp}.  However, if any exceptions were
792 flagged in the status word before @code{feupdateenv} was called, they
793 remain flagged after the call.  In other words, after @code{feupdateenv}
794 is called, the status word is the bitwise OR of the previous status word
795 and the one saved in @var{envp}.
796 @end deftypefun
798 @node Arithmetic Functions
799 @section Arithmetic Functions
801 The C library provides functions to do basic operations on
802 floating-point numbers.  These include absolute value, maximum and minimum,
803 normalization, bit twiddling, rounding, and a few others.
805 @menu
806 * Absolute Value::              Absolute values of integers and floats.
807 * Normalization Functions::     Extracting exponents and putting them back.
808 * Rounding Functions::          Rounding floats to integers.
809 * Remainder Functions::         Remainders on division, precisely defined.
810 * FP Bit Twiddling::            Sign bit adjustment.  Adding epsilon.
811 * FP Comparison Functions::     Comparisons without risk of exceptions.
812 * Misc FP Arithmetic::          Max, min, positive difference, multiply-add.
813 @end menu
815 @node Absolute Value
816 @subsection Absolute Value
817 @cindex absolute value functions
819 These functions are provided for obtaining the @dfn{absolute value} (or
820 @dfn{magnitude}) of a number.  The absolute value of a real number
821 @var{x} is @var{x} if @var{x} is positive, @minus{}@var{x} if @var{x} is
822 negative.  For a complex number @var{z}, whose real part is @var{x} and
823 whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt
824 (@var{x}*@var{x} + @var{y}*@var{y})}}.
826 @pindex math.h
827 @pindex stdlib.h
828 Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h};
829 @code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h}.
830 @code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}.
832 @comment stdlib.h
833 @comment ISO
834 @deftypefun int abs (int @var{number})
835 @comment stdlib.h
836 @comment ISO
837 @deftypefunx {long int} labs (long int @var{number})
838 @comment stdlib.h
839 @comment ISO
840 @deftypefunx {long long int} llabs (long long int @var{number})
841 These functions return the absolute value of @var{number}.
843 Most computers use a two's complement integer representation, in which
844 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
845 cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined.
847 @code{llabs} is new to @w{ISO C 9x}
848 @end deftypefun
850 @comment math.h
851 @comment ISO
852 @deftypefun double fabs (double @var{number})
853 @comment math.h
854 @comment ISO
855 @deftypefunx float fabsf (float @var{number})
856 @comment math.h
857 @comment ISO
858 @deftypefunx {long double} fabsl (long double @var{number})
859 This function returns the absolute value of the floating-point number
860 @var{number}.
861 @end deftypefun
863 @comment complex.h
864 @comment ISO
865 @deftypefun double cabs (complex double @var{z})
866 @comment complex.h
867 @comment ISO
868 @deftypefunx float cabsf (complex float @var{z})
869 @comment complex.h
870 @comment ISO
871 @deftypefunx {long double} cabsl (complex long double @var{z})
872 These functions return the absolute  value of the complex number @var{z}
873 (@pxref{Complex Numbers}).  The absolute value of a complex number is:
875 @smallexample
876 sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z}))
877 @end smallexample
879 This function should always be used instead of the direct formula
880 because it takes special care to avoid losing precision.  It may also
881 take advantage of hardware support for this operation. See @code{hypot}
882 in @ref{Exponents and Logarithms}.
883 @end deftypefun
885 @node Normalization Functions
886 @subsection Normalization Functions
887 @cindex normalization functions (floating-point)
889 The functions described in this section are primarily provided as a way
890 to efficiently perform certain low-level manipulations on floating point
891 numbers that are represented internally using a binary radix;
892 see @ref{Floating Point Concepts}.  These functions are required to
893 have equivalent behavior even if the representation does not use a radix
894 of 2, but of course they are unlikely to be particularly efficient in
895 those cases.
897 @pindex math.h
898 All these functions are declared in @file{math.h}.
900 @comment math.h
901 @comment ISO
902 @deftypefun double frexp (double @var{value}, int *@var{exponent})
903 @comment math.h
904 @comment ISO
905 @deftypefunx float frexpf (float @var{value}, int *@var{exponent})
906 @comment math.h
907 @comment ISO
908 @deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent})
909 These functions are used to split the number @var{value}
910 into a normalized fraction and an exponent.
912 If the argument @var{value} is not zero, the return value is @var{value}
913 times a power of two, and is always in the range 1/2 (inclusive) to 1
914 (exclusive).  The corresponding exponent is stored in
915 @code{*@var{exponent}}; the return value multiplied by 2 raised to this
916 exponent equals the original number @var{value}.
918 For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and
919 stores @code{4} in @code{exponent}.
921 If @var{value} is zero, then the return value is zero and
922 zero is stored in @code{*@var{exponent}}.
923 @end deftypefun
925 @comment math.h
926 @comment ISO
927 @deftypefun double ldexp (double @var{value}, int @var{exponent})
928 @comment math.h
929 @comment ISO
930 @deftypefunx float ldexpf (float @var{value}, int @var{exponent})
931 @comment math.h
932 @comment ISO
933 @deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent})
934 These functions return the result of multiplying the floating-point
935 number @var{value} by 2 raised to the power @var{exponent}.  (It can
936 be used to reassemble floating-point numbers that were taken apart
937 by @code{frexp}.)
939 For example, @code{ldexp (0.8, 4)} returns @code{12.8}.
940 @end deftypefun
942 The following functions, which come from BSD, provide facilities
943 equivalent to those of @code{ldexp} and @code{frexp}.
945 @comment math.h
946 @comment BSD
947 @deftypefun double logb (double @var{x})
948 @comment math.h
949 @comment BSD
950 @deftypefunx float logbf (float @var{x})
951 @comment math.h
952 @comment BSD
953 @deftypefunx {long double} logbl (long double @var{x})
954 These functions return the integer part of the base-2 logarithm of
955 @var{x}, an integer value represented in type @code{double}.  This is
956 the highest integer power of @code{2} contained in @var{x}.  The sign of
957 @var{x} is ignored.  For example, @code{logb (3.5)} is @code{1.0} and
958 @code{logb (4.0)} is @code{2.0}.
960 When @code{2} raised to this power is divided into @var{x}, it gives a
961 quotient between @code{1} (inclusive) and @code{2} (exclusive).
963 If @var{x} is zero, the return value is minus infinity if the machine
964 supports infinities, and a very small number if it does not.  If @var{x}
965 is infinity, the return value is infinity.
967 For finite @var{x}, the value returned by @code{logb} is one less than
968 the value that @code{frexp} would store into @code{*@var{exponent}}.
969 @end deftypefun
971 @comment math.h
972 @comment BSD
973 @deftypefun double scalb (double @var{value}, int @var{exponent})
974 @comment math.h
975 @comment BSD
976 @deftypefunx float scalbf (float @var{value}, int @var{exponent})
977 @comment math.h
978 @comment BSD
979 @deftypefunx {long double} scalbl (long double @var{value}, int @var{exponent})
980 The @code{scalb} function is the BSD name for @code{ldexp}.
981 @end deftypefun
983 @comment math.h
984 @comment BSD
985 @deftypefun {long long int} scalbn (double @var{x}, int n)
986 @comment math.h
987 @comment BSD
988 @deftypefunx {long long int} scalbnf (float @var{x}, int n)
989 @comment math.h
990 @comment BSD
991 @deftypefunx {long long int} scalbnl (long double @var{x}, int n)
992 @code{scalbn} is identical to @code{scalb}, except that the exponent
993 @var{n} is an @code{int} instead of a floating-point number.
994 @end deftypefun
996 @comment math.h
997 @comment BSD
998 @deftypefun {long long int} scalbln (double @var{x}, long int n)
999 @comment math.h
1000 @comment BSD
1001 @deftypefunx {long long int} scalblnf (float @var{x}, long int n)
1002 @comment math.h
1003 @comment BSD
1004 @deftypefunx {long long int} scalblnl (long double @var{x}, long int n)
1005 @code{scalbln} is identical to @code{scalb}, except that the exponent
1006 @var{n} is a @code{long int} instead of a floating-point number.
1007 @end deftypefun
1009 @comment math.h
1010 @comment BSD
1011 @deftypefun {long long int} significand (double @var{x})
1012 @comment math.h
1013 @comment BSD
1014 @deftypefunx {long long int} significandf (float @var{x})
1015 @comment math.h
1016 @comment BSD
1017 @deftypefunx {long long int} significandl (long double @var{x})
1018 @code{significand} returns the mantissa of @var{x} scaled to the range
1019 @math{[1, 2)}.
1020 It is equivalent to @w{@code{scalb (@var{x}, (double) -ilogb (@var{x}))}}.
1022 This function exists mainly for use in certain standardized tests
1023 of @w{IEEE 754} conformance.
1024 @end deftypefun
1026 @node Rounding Functions
1027 @subsection Rounding Functions
1028 @cindex converting floats to integers
1030 @pindex math.h
1031 The functions listed here perform operations such as rounding and
1032 truncation of floating-point values. Some of these functions convert
1033 floating point numbers to integer values.  They are all declared in
1034 @file{math.h}.
1036 You can also convert floating-point numbers to integers simply by
1037 casting them to @code{int}.  This discards the fractional part,
1038 effectively rounding towards zero.  However, this only works if the
1039 result can actually be represented as an @code{int}---for very large
1040 numbers, this is impossible.  The functions listed here return the
1041 result as a @code{double} instead to get around this problem.
1043 @comment math.h
1044 @comment ISO
1045 @deftypefun double ceil (double @var{x})
1046 @comment math.h
1047 @comment ISO
1048 @deftypefunx float ceilf (float @var{x})
1049 @comment math.h
1050 @comment ISO
1051 @deftypefunx {long double} ceill (long double @var{x})
1052 These functions round @var{x} upwards to the nearest integer,
1053 returning that value as a @code{double}.  Thus, @code{ceil (1.5)}
1054 is @code{2.0}.
1055 @end deftypefun
1057 @comment math.h
1058 @comment ISO
1059 @deftypefun double floor (double @var{x})
1060 @comment math.h
1061 @comment ISO
1062 @deftypefunx float floorf (float @var{x})
1063 @comment math.h
1064 @comment ISO
1065 @deftypefunx {long double} floorl (long double @var{x})
1066 These functions round @var{x} downwards to the nearest
1067 integer, returning that value as a @code{double}.  Thus, @code{floor
1068 (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
1069 @end deftypefun
1071 @comment math.h
1072 @comment ISO
1073 @deftypefun double trunc (double @var{x})
1074 @comment math.h
1075 @comment ISO
1076 @deftypefunx float truncf (float @var{x})
1077 @comment math.h
1078 @comment ISO
1079 @deftypefunx {long double} truncl (long double @var{x})
1080 @code{trunc} is another name for @code{floor}
1081 @end deftypefun
1083 @comment math.h
1084 @comment ISO
1085 @deftypefun double rint (double @var{x})
1086 @comment math.h
1087 @comment ISO
1088 @deftypefunx float rintf (float @var{x})
1089 @comment math.h
1090 @comment ISO
1091 @deftypefunx {long double} rintl (long double @var{x})
1092 These functions round @var{x} to an integer value according to the
1093 current rounding mode.  @xref{Floating Point Parameters}, for
1094 information about the various rounding modes.  The default
1095 rounding mode is to round to the nearest integer; some machines
1096 support other modes, but round-to-nearest is always used unless
1097 you explicitly select another.
1099 If @var{x} was not initially an integer, these functions raise the
1100 inexact exception.
1101 @end deftypefun
1103 @comment math.h
1104 @comment ISO
1105 @deftypefun double nearbyint (double @var{x})
1106 @comment math.h
1107 @comment ISO
1108 @deftypefunx float nearbyintf (float @var{x})
1109 @comment math.h
1110 @comment ISO
1111 @deftypefunx {long double} nearbyintl (long double @var{x})
1112 These functions return the same value as the @code{rint} functions, but
1113 do not raise the inexact exception if @var{x} is not an integer.
1114 @end deftypefun
1116 @comment math.h
1117 @comment ISO
1118 @deftypefun double round (double @var{x})
1119 @comment math.h
1120 @comment ISO
1121 @deftypefunx float roundf (float @var{x})
1122 @comment math.h
1123 @comment ISO
1124 @deftypefunx {long double} roundl (long double @var{x})
1125 These functions are similar to @code{rint}, but they round halfway
1126 cases away from zero instead of to the nearest even integer.
1127 @end deftypefun
1129 @comment math.h
1130 @comment ISO
1131 @deftypefun {long int} lrint (double @var{x})
1132 @comment math.h
1133 @comment ISO
1134 @deftypefunx {long int} lrintf (float @var{x})
1135 @comment math.h
1136 @comment ISO
1137 @deftypefunx {long int} lrintl (long double @var{x})
1138 These functions are just like @code{rint}, but they return a
1139 @code{long int} instead of a floating-point number.
1140 @end deftypefun
1142 @comment math.h
1143 @comment ISO
1144 @deftypefun {long long int} llrint (double @var{x})
1145 @comment math.h
1146 @comment ISO
1147 @deftypefunx {long long int} llrintf (float @var{x})
1148 @comment math.h
1149 @comment ISO
1150 @deftypefunx {long long int} llrintl (long double @var{x})
1151 These functions are just like @code{rint}, but they return a
1152 @code{long long int} instead of a floating-point number.
1153 @end deftypefun
1155 @comment math.h
1156 @comment ISO
1157 @deftypefun {long int} lround (double @var{x})
1158 @comment math.h
1159 @comment ISO
1160 @deftypefunx {long int} lroundf (float @var{x})
1161 @comment math.h
1162 @comment ISO
1163 @deftypefunx {long int} lroundl (long double @var{x})
1164 These functions are just like @code{round}, but they return a
1165 @code{long int} instead of a floating-point number.
1166 @end deftypefun
1168 @comment math.h
1169 @comment ISO
1170 @deftypefun {long long int} llround (double @var{x})
1171 @comment math.h
1172 @comment ISO
1173 @deftypefunx {long long int} llroundf (float @var{x})
1174 @comment math.h
1175 @comment ISO
1176 @deftypefunx {long long int} llroundl (long double @var{x})
1177 These functions are just like @code{round}, but they return a
1178 @code{long long int} instead of a floating-point number.
1179 @end deftypefun
1182 @comment math.h
1183 @comment ISO
1184 @deftypefun double modf (double @var{value}, double *@var{integer-part})
1185 @comment math.h
1186 @comment ISO
1187 @deftypefunx float modff (float @var{value}, float *@var{integer-part})
1188 @comment math.h
1189 @comment ISO
1190 @deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part})
1191 These functions break the argument @var{value} into an integer part and a
1192 fractional part (between @code{-1} and @code{1}, exclusive).  Their sum
1193 equals @var{value}.  Each of the parts has the same sign as @var{value},
1194 and the integer part is always rounded toward zero.
1196 @code{modf} stores the integer part in @code{*@var{integer-part}}, and
1197 returns the fractional part.  For example, @code{modf (2.5, &intpart)}
1198 returns @code{0.5} and stores @code{2.0} into @code{intpart}.
1199 @end deftypefun
1201 @node Remainder Functions
1202 @subsection Remainder Functions
1204 The functions in this section compute the remainder on division of two
1205 floating-point numbers.  Each is a little different; pick the one that
1206 suits your problem.
1208 @comment math.h
1209 @comment ISO
1210 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
1211 @comment math.h
1212 @comment ISO
1213 @deftypefunx float fmodf (float @var{numerator}, float @var{denominator})
1214 @comment math.h
1215 @comment ISO
1216 @deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator})
1217 These functions compute the remainder from the division of
1218 @var{numerator} by @var{denominator}.  Specifically, the return value is
1219 @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
1220 is the quotient of @var{numerator} divided by @var{denominator}, rounded
1221 towards zero to an integer.  Thus, @w{@code{fmod (6.5, 2.3)}} returns
1222 @code{1.9}, which is @code{6.5} minus @code{4.6}.
1224 The result has the same sign as the @var{numerator} and has magnitude
1225 less than the magnitude of the @var{denominator}.
1227 If @var{denominator} is zero, @code{fmod} signals a domain error.
1228 @end deftypefun
1230 @comment math.h
1231 @comment BSD
1232 @deftypefun double drem (double @var{numerator}, double @var{denominator})
1233 @comment math.h
1234 @comment BSD
1235 @deftypefunx float dremf (float @var{numerator}, float @var{denominator})
1236 @comment math.h
1237 @comment BSD
1238 @deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator})
1239 These functions are like @code{fmod} except that they rounds the
1240 internal quotient @var{n} to the nearest integer instead of towards zero
1241 to an integer.  For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
1242 which is @code{6.5} minus @code{6.9}.
1244 The absolute value of the result is less than or equal to half the
1245 absolute value of the @var{denominator}.  The difference between
1246 @code{fmod (@var{numerator}, @var{denominator})} and @code{drem
1247 (@var{numerator}, @var{denominator})} is always either
1248 @var{denominator}, minus @var{denominator}, or zero.
1250 If @var{denominator} is zero, @code{drem} signals a domain error.
1251 @end deftypefun
1253 @comment math.h
1254 @comment BSD
1255 @deftypefun double remainder (double @var{numerator}, double @var{denominator})
1256 @comment math.h
1257 @comment BSD
1258 @deftypefunx float remainderf (float @var{numerator}, float @var{denominator})
1259 @comment math.h
1260 @comment BSD
1261 @deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator})
1262 This function is another name for @code{drem}.
1263 @end deftypefun
1265 @node FP Bit Twiddling
1266 @subsection Setting and modifying single bits of FP values
1267 @cindex FP arithmetic
1269 There are some operations that are too complicated or expensive to
1270 perform by hand on floating-point numbers.  @w{ISO C 9x} defines
1271 functions to do these operations, which mostly involve changing single
1272 bits.
1274 @comment math.h
1275 @comment ISO
1276 @deftypefun double copysign (double @var{x}, double @var{y})
1277 @comment math.h
1278 @comment ISO
1279 @deftypefunx float copysignf (float @var{x}, float @var{y})
1280 @comment math.h
1281 @comment ISO
1282 @deftypefunx {long double} copysignl (long double @var{x}, long double @var{y})
1283 These functions return @var{x} but with the sign of @var{y}.  They work
1284 even if @var{x} or @var{y} are NaN or zero.  Both of these can carry a
1285 sign (although not all implementations support it) and this is one of
1286 the few operations that can tell the difference.
1288 @code{copysign} never raises an exception.
1289 @c except signalling NaNs
1291 This function is defined in @w{IEC 559} (and the appendix with
1292 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
1293 @end deftypefun
1295 @comment math.h
1296 @comment ISO
1297 @deftypefun int signbit (@emph{float-type} @var{x})
1298 @code{signbit} is a generic macro which can work on all floating-point
1299 types.  It returns a nonzero value if the value of @var{x} has its sign
1300 bit set.
1302 This is not the same as @code{x < 0.0}, because @w{IEEE 754} floating
1303 point allows zero to be signed.  The comparison @code{-0.0 < 0.0} is
1304 false, but @code{signbit (-0.0)} will return a nonzero value.
1305 @end deftypefun
1307 @comment math.h
1308 @comment ISO
1309 @deftypefun double nextafter (double @var{x}, double @var{y})
1310 @comment math.h
1311 @comment ISO
1312 @deftypefunx float nextafterf (float @var{x}, float @var{y})
1313 @comment math.h
1314 @comment ISO
1315 @deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y})
1316 The @code{nextafter} function returns the next representable neighbor of
1317 @var{x} in the direction towards @var{y}.  The size of the step between
1318 @var{x} and the result depends on the type of the result.  If
1319 @math{@var{x} = @var{y}} the function simply returns @var{x}.  If either
1320 value is @code{NaN}, @code{NaN} is returned.  Otherwise
1321 a value corresponding to the value of the least significant bit in the
1322 mantissa is added or subtracted, depending on the direction.
1323 @code{nextafter} will signal overflow or underflow if the result goes
1324 outside of the range of normalized numbers.
1326 This function is defined in @w{IEC 559} (and the appendix with
1327 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
1328 @end deftypefun
1330 @comment math.h
1331 @comment ISO
1332 @deftypefun {long long int} nextafterx (double @var{x}, long double @var{y})
1333 @comment math.h
1334 @comment ISO
1335 @deftypefunx {long long int} nextafterxf (float @var{x}, long double @var{y})
1336 @comment math.h
1337 @comment ISO
1338 @deftypefunx {long long int} nextafterxl (long double @var{x}, long double @var{y})
1339 These functions are identical to the corresponding versions of
1340 @code{nextafter} except that their second argument is a @code{long
1341 double}.
1342 @end deftypefun
1344 @cindex NaN
1345 @comment math.h
1346 @comment ISO
1347 @deftypefun double nan (const char *@var{tagp})
1348 @comment math.h
1349 @comment ISO
1350 @deftypefunx float nanf (const char *@var{tagp})
1351 @comment math.h
1352 @comment ISO
1353 @deftypefunx {long double} nanl (const char *@var{tagp})
1354 The @code{nan} function returns a representation of NaN, provided that
1355 NaN is supported by the target platform.
1356 @code{nan ("@var{n-char-sequence}")} is equivalent to
1357 @code{strtod ("NAN(@var{n-char-sequence})")}.
1359 The argument @var{tagp} is used in an unspecified manner.  On @w{IEEE
1360 754} systems, there are many representations of NaN, and @var{tagp}
1361 selects one.  On other systems it may do nothing.
1362 @end deftypefun
1364 @node FP Comparison Functions
1365 @subsection Floating-Point Comparison Functions
1366 @cindex unordered comparison
1368 The standard C comparison operators provoke exceptions when one or other
1369 of the operands is NaN.  For example,
1371 @smallexample
1372 int v = a < 1.0;
1373 @end smallexample
1375 @noindent
1376 will raise an exception if @var{a} is NaN.  (This does @emph{not}
1377 happen with @code{==} and @code{!=}; those merely return false and true,
1378 respectively, when NaN is examined.)  Frequently this exception is
1379 undesirable.  @w{ISO C 9x} therefore defines comparison functions that
1380 do not raise exceptions when NaN is examined.  All of the functions are
1381 implemented as macros which allow their arguments to be of any
1382 floating-point type.  The macros are guaranteed to evaluate their
1383 arguments only once.
1385 @comment math.h
1386 @comment ISO
1387 @deftypefn Macro int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1388 This macro determines whether the argument @var{x} is greater than
1389 @var{y}.  It is equivalent to @code{(@var{x}) > (@var{y})}, but no
1390 exception is raised if @var{x} or @var{y} are NaN.
1391 @end deftypefn
1393 @comment math.h
1394 @comment ISO
1395 @deftypefn Macro int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1396 This macro determines whether the argument @var{x} is greater than or
1397 equal to @var{y}.  It is equivalent to @code{(@var{x}) >= (@var{y})}, but no
1398 exception is raised if @var{x} or @var{y} are NaN.
1399 @end deftypefn
1401 @comment math.h
1402 @comment ISO
1403 @deftypefn Macro int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1404 This macro determines whether the argument @var{x} is less than @var{y}.
1405 It is equivalent to @code{(@var{x}) < (@var{y})}, but no exception is
1406 raised if @var{x} or @var{y} are NaN.
1407 @end deftypefn
1409 @comment math.h
1410 @comment ISO
1411 @deftypefn Macro int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1412 This macro determines whether the argument @var{x} is less than or equal
1413 to @var{y}.  It is equivalent to @code{(@var{x}) <= (@var{y})}, but no
1414 exception is raised if @var{x} or @var{y} are NaN.
1415 @end deftypefn
1417 @comment math.h
1418 @comment ISO
1419 @deftypefn Macro int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1420 This macro determines whether the argument @var{x} is less or greater
1421 than @var{y}.  It is equivalent to @code{(@var{x}) < (@var{y}) ||
1422 (@var{x}) > (@var{y})} (although it only evaluates @var{x} and @var{y}
1423 once), but no exception is raised if @var{x} or @var{y} are NaN.
1425 This macro is not equivalent to @code{@var{x} != @var{y}}, because that
1426 expression is true if @var{x} or @var{y} are NaN.
1427 @end deftypefn
1429 @comment math.h
1430 @comment ISO
1431 @deftypefn Macro int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1432 This macro determines whether its arguments are unordered.  In other
1433 words, it is true if @var{x} or @var{y} are NaN, and false otherwise.
1434 @end deftypefn
1436 Not all machines provide hardware support for these operations.  On
1437 machines that don't, the macros can be very slow.  Therefore, you should
1438 not use these functions when NaN is not a concern.
1440 @strong{Note:} There are no macros @code{isequal} or @code{isunequal}.
1441 They are unnecessary, because the @code{==} and @code{!=} operators do
1442 @emph{not} throw an exception if one or both of the operands are NaN.
1444 @node Misc FP Arithmetic
1445 @subsection Miscellaneous FP arithmetic functions
1446 @cindex minimum
1447 @cindex maximum
1448 @cindex positive difference
1449 @cindex multiply-add
1451 The functions in this section perform miscellaneous but common
1452 operations that are awkward to express with C operators.  On some
1453 processors these functions can use special machine instructions to
1454 perform these operations faster than the equivalent C code.
1456 @comment math.h
1457 @comment ISO
1458 @deftypefun double fmin (double @var{x}, double @var{y})
1459 @comment math.h
1460 @comment ISO
1461 @deftypefunx float fminf (float @var{x}, float @var{y})
1462 @comment math.h
1463 @comment ISO
1464 @deftypefunx {long double} fminl (long double @var{x}, long double @var{y})
1465 The @code{fmin} function returns the lesser of the two values @var{x}
1466 and @var{y}.  It is similar to the expression
1467 @smallexample
1468 ((x) < (y) ? (x) : (y))
1469 @end smallexample
1470 except that @var{x} and @var{y} are only evaluated once.
1472 If an argument is NaN, the other argument is returned.  If both arguments
1473 are NaN, NaN is returned.
1474 @end deftypefun
1476 @comment math.h
1477 @comment ISO
1478 @deftypefun double fmax (double @var{x}, double @var{y})
1479 @comment math.h
1480 @comment ISO
1481 @deftypefunx float fmaxf (float @var{x}, float @var{y})
1482 @comment math.h
1483 @comment ISO
1484 @deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y})
1485 The @code{fmax} function returns the greater of the two values @var{x}
1486 and @var{y}.
1488 If an argument is NaN, the other argument is returned.  If both arguments
1489 are NaN, NaN is returned.
1490 @end deftypefun
1492 @comment math.h
1493 @comment ISO
1494 @deftypefun double fdim (double @var{x}, double @var{y})
1495 @comment math.h
1496 @comment ISO
1497 @deftypefunx float fdimf (float @var{x}, float @var{y})
1498 @comment math.h
1499 @comment ISO
1500 @deftypefunx {long double} fdiml (long double @var{x}, long double @var{y})
1501 The @code{fdim} function returns the positive difference between
1502 @var{x} and @var{y}.  The positive difference is @math{@var{x} -
1503 @var{y}} if @var{x} is greater than @var{y}, and @math{0} otherwise.
1505 If @var{x}, @var{y}, or both are NaN, NaN is returned.
1506 @end deftypefun
1508 @comment math.h
1509 @comment ISO
1510 @deftypefun double fma (double @var{x}, double @var{y}, double @var{z})
1511 @comment math.h
1512 @comment ISO
1513 @deftypefunx float fmaf (float @var{x}, float @var{y}, float @var{z})
1514 @comment math.h
1515 @comment ISO
1516 @deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z})
1517 @cindex butterfly
1518 The @code{fma} function performs floating-point multiply-add.  This is
1519 the operation @math{(@var{x} @mul{} @var{y}) + @var{z}}, but the
1520 intermediate result is not rounded to the destination type.  This can
1521 sometimes improve the precision of a calculation.
1523 This function was introduced because some processors have a special
1524 instruction to perform multiply-add.  The C compiler cannot use it
1525 directly, because the expression @samp{x*y + z} is defined to round the
1526 intermediate result.  @code{fma} lets you choose when you want to round
1527 only once.
1529 @vindex FP_FAST_FMA
1530 On processors which do not implement multiply-add in hardware,
1531 @code{fma} can be very slow since it must avoid intermediate rounding.
1532 @file{math.h} defines the symbols @code{FP_FAST_FMA},
1533 @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL} when the corresponding
1534 version of @code{fma} is no slower than the expression @samp{x*y + z}.
1535 In the GNU C library, this always means the operation is implemented in
1536 hardware.
1537 @end deftypefun
1539 @node Complex Numbers
1540 @section Complex Numbers
1541 @pindex complex.h
1542 @cindex complex numbers
1544 @w{ISO C 9x} introduces support for complex numbers in C.  This is done
1545 with a new type qualifier, @code{complex}.  It is a keyword if and only
1546 if @file{complex.h} has been included.  There are three complex types,
1547 corresponding to the three real types:  @code{float complex},
1548 @code{double complex}, and @code{long double complex}.
1550 To construct complex numbers you need a way to indicate the imaginary
1551 part of a number.  There is no standard notation for an imaginary
1552 floating point constant.  Instead, @file{complex.h} defines two macros
1553 that can be used to create complex numbers.
1555 @deftypevr Macro {const float complex} _Complex_I
1556 This macro is a representation of the complex number ``@math{0+1i}''.
1557 Multiplying a real floating-point value by @code{_Complex_I} gives a
1558 complex number whose value is purely imaginary.  You can use this to
1559 construct complex constants:
1561 @smallexample
1562 @math{3.0 + 4.0i} = @code{3.0 + 4.0 * _Complex_I}
1563 @end smallexample
1565 Note that @code{_Complex_I * _Complex_I} has the value @code{-1}, but
1566 the type of that value is @code{complex}.
1567 @end deftypevr
1569 @c Put this back in when gcc supports _Imaginary_I.  It's too confusing.
1570 @ignore
1571 @noindent
1572 Without an optimizing compiler this is more expensive than the use of
1573 @code{_Imaginary_I} but with is better than nothing.  You can avoid all
1574 the hassles if you use the @code{I} macro below if the name is not
1575 problem.
1577 @deftypevr Macro {const float imaginary} _Imaginary_I
1578 This macro is a representation of the value ``@math{1i}''.  I.e., it is
1579 the value for which
1581 @smallexample
1582 _Imaginary_I * _Imaginary_I = -1
1583 @end smallexample
1585 @noindent
1586 The result is not of type @code{float imaginary} but instead @code{float}.
1587 One can use it to easily construct complex number like in
1589 @smallexample
1590 3.0 - _Imaginary_I * 4.0
1591 @end smallexample
1593 @noindent
1594 which results in the complex number with a real part of 3.0 and a
1595 imaginary part -4.0.
1596 @end deftypevr
1597 @end ignore
1599 @noindent
1600 @code{_Complex_I} is a bit of a mouthful.  @file{complex.h} also defines
1601 a shorter name for the same constant.
1603 @deftypevr Macro {const float complex} I
1604 This macro has exactly the same value as @code{_Complex_I}.  Most of the
1605 time it is preferable.  However, it causes problems if you want to use
1606 the identifier @code{I} for something else.  You can safely write
1608 @smallexample
1609 #include <complex.h>
1610 #undef I
1611 @end smallexample
1613 @noindent
1614 if you need @code{I} for your own purposes.  (In that case we recommend
1615 you also define some other short name for @code{_Complex_I}, such as
1616 @code{J}.)
1618 @ignore
1619 If the implementation does not support the @code{imaginary} types
1620 @code{I} is defined as @code{_Complex_I} which is the second best
1621 solution.  It still can be used in the same way but requires a most
1622 clever compiler to get the same results.
1623 @end ignore
1624 @end deftypevr
1626 @node Operations on Complex
1627 @section Projections, Conjugates, and Decomposing of Complex Numbers
1628 @cindex project complex numbers
1629 @cindex conjugate complex numbers
1630 @cindex decompose complex numbers
1631 @pindex complex.h
1633 @w{ISO C 9x} also defines functions that perform basic operations on
1634 complex numbers, such as decomposition and conjugation.  The prototypes
1635 for all these functions are in @file{complex.h}.  All functions are
1636 available in three variants, one for each of the three complex types.
1638 @comment complex.h
1639 @comment ISO
1640 @deftypefun double creal (complex double @var{z})
1641 @comment complex.h
1642 @comment ISO
1643 @deftypefunx float crealf (complex float @var{z})
1644 @comment complex.h
1645 @comment ISO
1646 @deftypefunx {long double} creall (complex long double @var{z})
1647 These functions return the real part of the complex number @var{z}.
1648 @end deftypefun
1650 @comment complex.h
1651 @comment ISO
1652 @deftypefun double cimag (complex double @var{z})
1653 @comment complex.h
1654 @comment ISO
1655 @deftypefunx float cimagf (complex float @var{z})
1656 @comment complex.h
1657 @comment ISO
1658 @deftypefunx {long double} cimagl (complex long double @var{z})
1659 These functions return the imaginary part of the complex number @var{z}.
1660 @end deftypefun
1662 @comment complex.h
1663 @comment ISO
1664 @deftypefun {complex double} conj (complex double @var{z})
1665 @comment complex.h
1666 @comment ISO
1667 @deftypefunx {complex float} conjf (complex float @var{z})
1668 @comment complex.h
1669 @comment ISO
1670 @deftypefunx {complex long double} conjl (complex long double @var{z})
1671 These functions return the conjugate value of the complex number
1672 @var{z}.  The conjugate of a complex number has the same real part and a
1673 negated imaginary part.  In other words, @samp{conj(a + bi) = a + -bi}.
1674 @end deftypefun
1676 @comment complex.h
1677 @comment ISO
1678 @deftypefun double carg (complex double @var{z})
1679 @comment complex.h
1680 @comment ISO
1681 @deftypefunx float cargf (complex float @var{z})
1682 @comment complex.h
1683 @comment ISO
1684 @deftypefunx {long double} cargl (complex long double @var{z})
1685 These functions return the argument of the complex number @var{z}.
1686 The argument of a complex number is the angle in the complex plane
1687 between the positive real axis and a line passing through zero and the
1688 number.  This angle is measured in the usual fashion and ranges from @math{0}
1689 to @math{2@pi{}}.
1691 @code{carg} has a branch cut along the positive real axis.
1692 @end deftypefun
1694 @comment complex.h
1695 @comment ISO
1696 @deftypefun {complex double} cproj (complex double @var{z})
1697 @comment complex.h
1698 @comment ISO
1699 @deftypefunx {complex float} cprojf (complex float @var{z})
1700 @comment complex.h
1701 @comment ISO
1702 @deftypefunx {complex long double} cprojl (complex long double @var{z})
1703 These functions return the projection of the complex value @var{z} onto
1704 the Riemann sphere.  Values with a infinite imaginary part are projected
1705 to positive infinity on the real axis, even if the real part is NaN.  If
1706 the real part is infinite, the result is equivalent to
1708 @smallexample
1709 INFINITY + I * copysign (0.0, cimag (z))
1710 @end smallexample
1711 @end deftypefun
1713 @node Integer Division
1714 @section Integer Division
1715 @cindex integer division functions
1717 This section describes functions for performing integer division.  These
1718 functions are redundant when GNU CC is used, because in GNU C the
1719 @samp{/} operator always rounds towards zero.  But in other C
1720 implementations, @samp{/} may round differently with negative arguments.
1721 @code{div} and @code{ldiv} are useful because they specify how to round
1722 the quotient: towards zero.  The remainder has the same sign as the
1723 numerator.
1725 These functions are specified to return a result @var{r} such that the value
1726 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
1727 @var{numerator}.
1729 @pindex stdlib.h
1730 To use these facilities, you should include the header file
1731 @file{stdlib.h} in your program.
1733 @comment stdlib.h
1734 @comment ISO
1735 @deftp {Data Type} div_t
1736 This is a structure type used to hold the result returned by the @code{div}
1737 function.  It has the following members:
1739 @table @code
1740 @item int quot
1741 The quotient from the division.
1743 @item int rem
1744 The remainder from the division.
1745 @end table
1746 @end deftp
1748 @comment stdlib.h
1749 @comment ISO
1750 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
1751 This function @code{div} computes the quotient and remainder from
1752 the division of @var{numerator} by @var{denominator}, returning the
1753 result in a structure of type @code{div_t}.
1755 If the result cannot be represented (as in a division by zero), the
1756 behavior is undefined.
1758 Here is an example, albeit not a very useful one.
1760 @smallexample
1761 div_t result;
1762 result = div (20, -6);
1763 @end smallexample
1765 @noindent
1766 Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
1767 @end deftypefun
1769 @comment stdlib.h
1770 @comment ISO
1771 @deftp {Data Type} ldiv_t
1772 This is a structure type used to hold the result returned by the @code{ldiv}
1773 function.  It has the following members:
1775 @table @code
1776 @item long int quot
1777 The quotient from the division.
1779 @item long int rem
1780 The remainder from the division.
1781 @end table
1783 (This is identical to @code{div_t} except that the components are of
1784 type @code{long int} rather than @code{int}.)
1785 @end deftp
1787 @comment stdlib.h
1788 @comment ISO
1789 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
1790 The @code{ldiv} function is similar to @code{div}, except that the
1791 arguments are of type @code{long int} and the result is returned as a
1792 structure of type @code{ldiv_t}.
1793 @end deftypefun
1795 @comment stdlib.h
1796 @comment ISO
1797 @deftp {Data Type} lldiv_t
1798 This is a structure type used to hold the result returned by the @code{lldiv}
1799 function.  It has the following members:
1801 @table @code
1802 @item long long int quot
1803 The quotient from the division.
1805 @item long long int rem
1806 The remainder from the division.
1807 @end table
1809 (This is identical to @code{div_t} except that the components are of
1810 type @code{long long int} rather than @code{int}.)
1811 @end deftp
1813 @comment stdlib.h
1814 @comment ISO
1815 @deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator})
1816 The @code{lldiv} function is like the @code{div} function, but the
1817 arguments are of type @code{long long int} and the result is returned as
1818 a structure of type @code{lldiv_t}.
1820 The @code{lldiv} function was added in @w{ISO C 9x}.
1821 @end deftypefun
1824 @node Parsing of Numbers
1825 @section Parsing of Numbers
1826 @cindex parsing numbers (in formatted input)
1827 @cindex converting strings to numbers
1828 @cindex number syntax, parsing
1829 @cindex syntax, for reading numbers
1831 This section describes functions for ``reading'' integer and
1832 floating-point numbers from a string.  It may be more convenient in some
1833 cases to use @code{sscanf} or one of the related functions; see
1834 @ref{Formatted Input}.  But often you can make a program more robust by
1835 finding the tokens in the string by hand, then converting the numbers
1836 one by one.
1838 @menu
1839 * Parsing of Integers::         Functions for conversion of integer values.
1840 * Parsing of Floats::           Functions for conversion of floating-point
1841                                  values.
1842 @end menu
1844 @node Parsing of Integers
1845 @subsection Parsing of Integers
1847 @pindex stdlib.h
1848 These functions are declared in @file{stdlib.h}.
1850 @comment stdlib.h
1851 @comment ISO
1852 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
1853 The @code{strtol} (``string-to-long'') function converts the initial
1854 part of @var{string} to a signed integer, which is returned as a value
1855 of type @code{long int}.
1857 This function attempts to decompose @var{string} as follows:
1859 @itemize @bullet
1860 @item
1861 A (possibly empty) sequence of whitespace characters.  Which characters
1862 are whitespace is determined by the @code{isspace} function
1863 (@pxref{Classification of Characters}).  These are discarded.
1865 @item
1866 An optional plus or minus sign (@samp{+} or @samp{-}).
1868 @item
1869 A nonempty sequence of digits in the radix specified by @var{base}.
1871 If @var{base} is zero, decimal radix is assumed unless the series of
1872 digits begins with @samp{0} (specifying octal radix), or @samp{0x} or
1873 @samp{0X} (specifying hexadecimal radix); in other words, the same
1874 syntax used for integer constants in C.
1876 Otherwise @var{base} must have a value between @code{2} and @code{35}.
1877 If @var{base} is @code{16}, the digits may optionally be preceded by
1878 @samp{0x} or @samp{0X}.  If base has no legal value the value returned
1879 is @code{0l} and the global variable @code{errno} is set to @code{EINVAL}.
1881 @item
1882 Any remaining characters in the string.  If @var{tailptr} is not a null
1883 pointer, @code{strtol} stores a pointer to this tail in
1884 @code{*@var{tailptr}}.
1885 @end itemize
1887 If the string is empty, contains only whitespace, or does not contain an
1888 initial substring that has the expected syntax for an integer in the
1889 specified @var{base}, no conversion is performed.  In this case,
1890 @code{strtol} returns a value of zero and the value stored in
1891 @code{*@var{tailptr}} is the value of @var{string}.
1893 In a locale other than the standard @code{"C"} locale, this function
1894 may recognize additional implementation-dependent syntax.
1896 If the string has valid syntax for an integer but the value is not
1897 representable because of overflow, @code{strtol} returns either
1898 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as
1899 appropriate for the sign of the value.  It also sets @code{errno}
1900 to @code{ERANGE} to indicate there was overflow.
1902 You should not check for errors by examining the return value of
1903 @code{strtol}, because the string might be a valid representation of
1904 @code{0l}, @code{LONG_MAX}, or @code{LONG_MIN}.  Instead, check whether
1905 @var{tailptr} points to what you expect after the number
1906 (e.g. @code{'\0'} if the string should end after the number).  You also
1907 need to clear @var{errno} before the call and check it afterward, in
1908 case there was overflow.
1910 There is an example at the end of this section.
1911 @end deftypefun
1913 @comment stdlib.h
1914 @comment ISO
1915 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
1916 The @code{strtoul} (``string-to-unsigned-long'') function is like
1917 @code{strtol} except it returns an @code{unsigned long int} value.  If
1918 the number has a leading @samp{-} sign, the return value is negated.
1919 The syntax is the same as described above for @code{strtol}.  The value
1920 returned on overflow is @code{ULONG_MAX} (@pxref{Range of
1921 Type}).
1923 @code{strtoul} sets @var{errno} to @code{EINVAL} if @var{base} is out of
1924 range, or @code{ERANGE} on overflow.
1925 @end deftypefun
1927 @comment stdlib.h
1928 @comment ISO
1929 @deftypefun {long long int} strtoll (const char *@var{string}, char **@var{tailptr}, int @var{base})
1930 The @code{strtoll} function is like @code{strtol} except that it returns
1931 a @code{long long int} value, and accepts numbers with a correspondingly
1932 larger range.
1934 If the string has valid syntax for an integer but the value is not
1935 representable because of overflow, @code{strtoll} returns either
1936 @code{LONG_LONG_MAX} or @code{LONG_LONG_MIN} (@pxref{Range of Type}), as
1937 appropriate for the sign of the value.  It also sets @code{errno} to
1938 @code{ERANGE} to indicate there was overflow.
1940 The @code{strtoll} function was introduced in @w{ISO C 9x}.
1941 @end deftypefun
1943 @comment stdlib.h
1944 @comment BSD
1945 @deftypefun {long long int} strtoq (const char *@var{string}, char **@var{tailptr}, int @var{base})
1946 @code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}.
1947 @end deftypefun
1949 @comment stdlib.h
1950 @comment ISO
1951 @deftypefun {unsigned long long int} strtoull (const char *@var{string}, char **@var{tailptr}, int @var{base})
1952 The @code{strtoull} function is like @code{strtoul} except that it
1953 returns an @code{unsigned long long int}.  The value returned on overflow
1954 is @code{ULONG_LONG_MAX} (@pxref{Range of Type}).
1956 The @code{strtoull} function was introduced in @w{ISO C 9x}.
1957 @end deftypefun
1959 @comment stdlib.h
1960 @comment BSD
1961 @deftypefun {unsigned long long int} strtouq (const char *@var{string}, char **@var{tailptr}, int @var{base})
1962 @code{strtouq} is the BSD name for @code{strtoull}.
1963 @end deftypefun
1965 @comment stdlib.h
1966 @comment ISO
1967 @deftypefun {long int} atol (const char *@var{string})
1968 This function is similar to the @code{strtol} function with a @var{base}
1969 argument of @code{10}, except that it need not detect overflow errors.
1970 The @code{atol} function is provided mostly for compatibility with
1971 existing code; using @code{strtol} is more robust.
1972 @end deftypefun
1974 @comment stdlib.h
1975 @comment ISO
1976 @deftypefun int atoi (const char *@var{string})
1977 This function is like @code{atol}, except that it returns an @code{int}.
1978 The @code{atoi} function is also considered obsolete; use @code{strtol}
1979 instead.
1980 @end deftypefun
1982 @comment stdlib.h
1983 @comment ISO
1984 @deftypefun {long long int} atoll (const char *@var{string})
1985 This function is similar to @code{atol}, except it returns a @code{long
1986 long int}.
1988 The @code{atoll} function was introduced in @w{ISO C 9x}.  It too is
1989 obsolete (despite having just been added); use @code{strtoll} instead.
1990 @end deftypefun
1992 @c !!! please fact check this paragraph -zw
1993 @findex strtol_l
1994 @findex strtoul_l
1995 @findex strtoll_l
1996 @findex strtoull_l
1997 @cindex parsing numbers and locales
1998 @cindex locales, parsing numbers and
1999 Some locales specify a printed syntax for numbers other than the one
2000 that these functions understand.  If you need to read numbers formatted
2001 in some other locale, you can use the @code{strtoX_l} functions.  Each
2002 of the @code{strtoX} functions has a counterpart with @samp{_l} added to
2003 its name.  The @samp{_l} counterparts take an additional argument: a
2004 pointer to an @code{locale_t} structure, which describes how the numbers
2005 to be read are formatted.  @xref{Locales}.
2007 @strong{Portability Note:} These functions are all GNU extensions.  You
2008 can also use @code{scanf} or its relatives, which have the @samp{'} flag
2009 for parsing numeric input according to the current locale
2010 (@pxref{Numeric Input Conversions}).  This feature is standard.
2012 Here is a function which parses a string as a sequence of integers and
2013 returns the sum of them:
2015 @smallexample
2017 sum_ints_from_string (char *string)
2019   int sum = 0;
2021   while (1) @{
2022     char *tail;
2023     int next;
2025     /* @r{Skip whitespace by hand, to detect the end.}  */
2026     while (isspace (*string)) string++;
2027     if (*string == 0)
2028       break;
2030     /* @r{There is more nonwhitespace,}  */
2031     /* @r{so it ought to be another number.}  */
2032     errno = 0;
2033     /* @r{Parse it.}  */
2034     next = strtol (string, &tail, 0);
2035     /* @r{Add it in, if not overflow.}  */
2036     if (errno)
2037       printf ("Overflow\n");
2038     else
2039       sum += next;
2040     /* @r{Advance past it.}  */
2041     string = tail;
2042   @}
2044   return sum;
2046 @end smallexample
2048 @node Parsing of Floats
2049 @subsection Parsing of Floats
2051 @pindex stdlib.h
2052 These functions are declared in @file{stdlib.h}.
2054 @comment stdlib.h
2055 @comment ISO
2056 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
2057 The @code{strtod} (``string-to-double'') function converts the initial
2058 part of @var{string} to a floating-point number, which is returned as a
2059 value of type @code{double}.
2061 This function attempts to decompose @var{string} as follows:
2063 @itemize @bullet
2064 @item
2065 A (possibly empty) sequence of whitespace characters.  Which characters
2066 are whitespace is determined by the @code{isspace} function
2067 (@pxref{Classification of Characters}).  These are discarded.
2069 @item
2070 An optional plus or minus sign (@samp{+} or @samp{-}).
2072 @item
2073 A nonempty sequence of digits optionally containing a decimal-point
2074 character---normally @samp{.}, but it depends on the locale
2075 (@pxref{General Numeric}).
2077 @item
2078 An optional exponent part, consisting of a character @samp{e} or
2079 @samp{E}, an optional sign, and a sequence of digits.
2081 @item
2082 Any remaining characters in the string.  If @var{tailptr} is not a null
2083 pointer, a pointer to this tail of the string is stored in
2084 @code{*@var{tailptr}}.
2085 @end itemize
2087 If the string is empty, contains only whitespace, or does not contain an
2088 initial substring that has the expected syntax for a floating-point
2089 number, no conversion is performed.  In this case, @code{strtod} returns
2090 a value of zero and the value returned in @code{*@var{tailptr}} is the
2091 value of @var{string}.
2093 In a locale other than the standard @code{"C"} or @code{"POSIX"} locales,
2094 this function may recognize additional locale-dependent syntax.
2096 If the string has valid syntax for a floating-point number but the value
2097 is outside the range of a @code{double}, @code{strtod} will signal
2098 overflow or underflow as described in @ref{Math Error Reporting}.
2100 @code{strtod} recognizes four special input strings.  The strings
2101 @code{"inf"} and @code{"infinity"} are converted to @math{@infinity{}},
2102 or to the largest representable value if the floating-point format
2103 doesn't support infinities.  You can prepend a @code{"+"} or @code{"-"}
2104 to specify the sign.  Case is ignored when scanning these strings.
2106 The strings @code{"nan"} and @code{"nan(@var{chars...})"} are converted
2107 to NaN.  Again, case is ignored.  If @var{chars...} are provided, they
2108 are used in some unspecified fashion to select a particular
2109 representation of NaN (there can be several).
2111 Since zero is a valid result as well as the value returned on error, you
2112 should check for errors in the same way as for @code{strtol}, by
2113 examining @var{errno} and @var{tailptr}.
2114 @end deftypefun
2116 @comment stdlib.h
2117 @comment GNU
2118 @deftypefun float strtof (const char *@var{string}, char **@var{tailptr})
2119 @comment stdlib.h
2120 @comment GNU
2121 @deftypefunx {long double} strtold (const char *@var{string}, char **@var{tailptr})
2122 These functions are analogous to @code{strtod}, but return @code{float}
2123 and @code{long double} values respectively.  They report errors in the
2124 same way as @code{strtod}.  @code{strtof} can be substantially faster
2125 than @code{strtod}, but has less precision; conversely, @code{strtold}
2126 can be much slower but has more precision (on systems where @code{long
2127 double} is a separate type).
2129 These functions are GNU extensions.
2130 @end deftypefun
2132 @comment stdlib.h
2133 @comment ISO
2134 @deftypefun double atof (const char *@var{string})
2135 This function is similar to the @code{strtod} function, except that it
2136 need not detect overflow and underflow errors.  The @code{atof} function
2137 is provided mostly for compatibility with existing code; using
2138 @code{strtod} is more robust.
2139 @end deftypefun
2141 The GNU C library also provides @samp{_l} versions of thse functions,
2142 which take an additional argument, the locale to use in conversion.
2143 @xref{Parsing of Integers}.
2145 @node System V Number Conversion
2146 @section Old-fashioned System V number-to-string functions
2148 The old @w{System V} C library provided three functions to convert
2149 numbers to strings, with unusual and hard-to-use semantics.  The GNU C
2150 library also provides these functions and some natural extensions.
2152 These functions are only available in glibc and on systems descended
2153 from AT&T Unix.  Therefore, unless these functions do precisely what you
2154 need, it is better to use @code{sprintf}, which is standard.
2156 All these functions are defined in @file{stdlib.h}.
2158 @comment stdlib.h
2159 @comment SVID, Unix98
2160 @deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2161 The function @code{ecvt} converts the floating-point number @var{value}
2162 to a string with at most @var{ndigit} decimal digits.
2163 The returned string contains no decimal point or sign. The first
2164 digit of the string is non-zero (unless @var{value} is actually zero)
2165 and the last digit is rounded to nearest.  @var{decpt} is set to the
2166 index in the string of the first digit after the decimal point.
2167 @var{neg} is set to a nonzero value if @var{value} is negative, zero
2168 otherwise.
2170 The returned string is statically allocated and overwritten by each call
2171 to @code{ecvt}.
2173 If @var{value} is zero, it's implementation defined whether @var{decpt} is
2174 @code{0} or @code{1}.
2176 For example: @code{ecvt (12.3, 5, &decpt, &neg)} returns @code{"12300"}
2177 and sets @var{decpt} to @code{2} and @var{neg} to @code{0}.
2178 @end deftypefun
2180 @comment stdlib.h
2181 @comment SVID, Unix98
2182 @deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int @var{decpt}, int *@var{neg})
2183 The function @code{fcvt} is like @code{ecvt}, but @var{ndigit} specifies
2184 the number of digits after the decimal point.  If @var{ndigit} is less
2185 than zero, @var{value} is rounded to the @math{@var{ndigit}+1}'th place to the
2186 left of the decimal point.  For example, if @var{ndigit} is @code{-1},
2187 @var{value} will be rounded to the nearest 10.  If @var{ndigit} is
2188 negative and larger than the number of digits to the left of the decimal
2189 point in @var{value}, @var{value} will be rounded to one significant digit.
2191 The returned string is statically allocated and overwritten by each call
2192 to @code{fcvt}.
2193 @end deftypefun
2195 @comment stdlib.h
2196 @comment SVID, Unix98
2197 @deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf})
2198 @code{gcvt} is functionally equivalent to @samp{sprintf(buf, "%*g",
2199 ndigit, value}.  It is provided only for compatibility's sake.  It
2200 returns @var{buf}.
2201 @end deftypefun
2203 As extensions, the GNU C library provides versions of these three
2204 functions that take @code{long double} arguments.
2206 @comment stdlib.h
2207 @comment GNU
2208 @deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2209 This function is equivalent to @code{ecvt} except that it
2210 takes a @code{long double} for the first parameter.
2211 @end deftypefun
2213 @comment stdlib.h
2214 @comment GNU
2215 @deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int @var{decpt}, int *@var{neg})
2216 This function is equivalent to @code{fcvt} except that it
2217 takes a @code{long double} for the first parameter.
2218 @end deftypefun
2220 @comment stdlib.h
2221 @comment GNU
2222 @deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf})
2223 This function is equivalent to @code{gcvt} except that it
2224 takes a @code{long double} for the first parameter.
2225 @end deftypefun
2228 @cindex gcvt_r
2229 The @code{ecvt} and @code{fcvt} functions, and their @code{long double}
2230 equivalents, all return a string located in a static buffer which is
2231 overwritten by the next call to the function.  The GNU C library
2232 provides another set of extended functions which write the converted
2233 string into a user-supplied buffer.  These have the conventional
2234 @code{_r} suffix.
2236 @code{gcvt_r} is not necessary, because @code{gcvt} already uses a
2237 user-supplied buffer.
2239 @comment stdlib.h
2240 @comment GNU
2241 @deftypefun {char *} ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2242 The @code{ecvt_r} function is the same as @code{ecvt}, except
2243 that it places its result into the user-specified buffer pointed to by
2244 @var{buf}, with length @var{len}.
2246 This function is a GNU extension.
2247 @end deftypefun
2249 @comment stdlib.h
2250 @comment SVID, Unix98
2251 @deftypefun {char *} fcvt_r (double @var{value}, int @var{ndigit}, int @var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2252 The @code{fcvt_r} function is the same as @code{fcvt}, except
2253 that it places its result into the user-specified buffer pointed to by
2254 @var{buf}, with length @var{len}.
2256 This function is a GNU extension.
2257 @end deftypefun
2259 @comment stdlib.h
2260 @comment GNU
2261 @deftypefun {char *} qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2262 The @code{qecvt_r} function is the same as @code{qecvt}, except
2263 that it places its result into the user-specified buffer pointed to by
2264 @var{buf}, with length @var{len}.
2266 This function is a GNU extension.
2267 @end deftypefun
2269 @comment stdlib.h
2270 @comment GNU
2271 @deftypefun {char *} qfcvt_r (long double @var{value}, int @var{ndigit}, int @var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2272 The @code{qfcvt_r} function is the same as @code{qfcvt}, except
2273 that it places its result into the user-specified buffer pointed to by
2274 @var{buf}, with length @var{len}.
2276 This function is a GNU extension.
2277 @end deftypefun