(argz_delete): Fix prototype.
[kopensolaris-gnu/glibc.git] / manual / arith.texi
1 @node Arithmetic, Date and Time, Mathematics, Top
2 @c %MENU% Low level arithmetic functions
3 @chapter Arithmetic Functions
4
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}.
10
11 @menu
12 * Integers::                    Basic integer types and concepts
13 * Integer Division::            Integer division with guaranteed rounding.
14 * Floating Point Numbers::      Basic concepts.  IEEE 754.
15 * Floating Point Classes::      The five kinds of floating-point number.
16 * Floating Point Errors::       When something goes wrong in a calculation.
17 * Rounding::                    Controlling how results are rounded.
18 * Control Functions::           Saving and restoring the FPU's state.
19 * Arithmetic Functions::        Fundamental operations provided by the library.
20 * Complex Numbers::             The types.  Writing complex constants.
21 * Operations on Complex::       Projection, conjugation, decomposition.
22 * Parsing of Numbers::          Converting strings to numbers.
23 * System V Number Conversion::  An archaic way to convert numbers to strings.
24 @end menu
25
26 @node Integers
27 @section Integers
28 @cindex integer
29
30 The C language defines several integer data types: integer, short integer,
31 long integer, and character, all in both signed and unsigned varieties.
32 The GNU C compiler extends the language to contain long long integers
33 as well.
34 @cindex signedness
35
36 The C integer types were intended to allow code to be portable among
37 machines with different inherent data sizes (word sizes), so each type
38 may have different ranges on different machines.  The problem with
39 this is that a program often needs to be written for a particular range
40 of integers, and sometimes must be written for a particular size of
41 storage, regardless of what machine the program runs on.
42
43 To address this problem, the GNU C library contains C type definitions
44 you can use to declare integers that meet your exact needs.  Because the
45 GNU C library header files are customized to a specific machine, your
46 program source code doesn't have to be.
47
48 These @code{typedef}s are in @file{stdint.h}.
49 @pindex stdint.h
50
51 If you require that an integer be represented in exactly N bits, use one
52 of the following types, with the obvious mapping to bit size and signedness:
53
54 @itemize @bullet
55 @item int8_t
56 @item int16_t
57 @item int32_t
58 @item int64_t
59 @item uint8_t
60 @item uint16_t
61 @item uint32_t
62 @item uint64_t
63 @end itemize
64
65 If your C compiler and target machine do not allow integers of a certain
66 size, the corresponding above type does not exist.
67
68 If you don't need a specific storage size, but want the smallest data
69 structure with @emph{at least} N bits, use one of these:
70
71 @itemize @bullet
72 @item int_least8_t
73 @item int_least16_t
74 @item int_least32_t
75 @item int_least64_t
76 @item uint_least8_t
77 @item uint_least16_t
78 @item uint_least32_t
79 @item uint_least64_t
80 @end itemize
81
82 If you don't need a specific storage size, but want the data structure
83 that allows the fastest access while having at least N bits (and
84 among data structures with the same access speed, the smallest one), use
85 one of these:
86
87 @itemize @bullet
88 @item int_fast8_t
89 @item int_fast16_t
90 @item int_fast32_t
91 @item int_fast64_t
92 @item uint_fast8_t
93 @item uint_fast16_t
94 @item uint_fast32_t
95 @item uint_fast64_t
96 @end itemize
97
98 If you want an integer with the widest range possible on the platform on
99 which it is being used, use one of the following.  If you use these,
100 you should write code that takes into account the variable size and range
101 of the integer.
102
103 @itemize @bullet
104 @item intmax_t
105 @item uintmax_t
106 @end itemize
107
108 The GNU C library also provides macros that tell you the maximum and
109 minimum possible values for each integer data type.  The macro names
110 follow these examples: @code{INT32_MAX}, @code{UINT8_MAX},
111 @code{INT_FAST32_MIN}, @code{INT_LEAST64_MIN}, @code{UINTMAX_MAX},
112 @code{INTMAX_MAX}, @code{INTMAX_MIN}.  Note that there are no macros for
113 unsigned integer minima.  These are always zero.
114 @cindex maximum possible integer
115 @cindex minimum possible integer
116
117 There are similar macros for use with C's built in integer types which
118 should come with your C compiler.  These are described in @ref{Data Type
119 Measurements}.
120
121 Don't forget you can use the C @code{sizeof} function with any of these
122 data types to get the number of bytes of storage each uses.
123
124
125 @node Integer Division
126 @section Integer Division
127 @cindex integer division functions
128
129 This section describes functions for performing integer division.  These
130 functions are redundant when GNU CC is used, because in GNU C the
131 @samp{/} operator always rounds towards zero.  But in other C
132 implementations, @samp{/} may round differently with negative arguments.
133 @code{div} and @code{ldiv} are useful because they specify how to round
134 the quotient: towards zero.  The remainder has the same sign as the
135 numerator.
136
137 These functions are specified to return a result @var{r} such that the value
138 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
139 @var{numerator}.
140
141 @pindex stdlib.h
142 To use these facilities, you should include the header file
143 @file{stdlib.h} in your program.
144
145 @comment stdlib.h
146 @comment ISO
147 @deftp {Data Type} div_t
148 This is a structure type used to hold the result returned by the @code{div}
149 function.  It has the following members:
150
151 @table @code
152 @item int quot
153 The quotient from the division.
154
155 @item int rem
156 The remainder from the division.
157 @end table
158 @end deftp
159
160 @comment stdlib.h
161 @comment ISO
162 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
163 This function @code{div} computes the quotient and remainder from
164 the division of @var{numerator} by @var{denominator}, returning the
165 result in a structure of type @code{div_t}.
166
167 If the result cannot be represented (as in a division by zero), the
168 behavior is undefined.
169
170 Here is an example, albeit not a very useful one.
171
172 @smallexample
173 div_t result;
174 result = div (20, -6);
175 @end smallexample
176
177 @noindent
178 Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
179 @end deftypefun
180
181 @comment stdlib.h
182 @comment ISO
183 @deftp {Data Type} ldiv_t
184 This is a structure type used to hold the result returned by the @code{ldiv}
185 function.  It has the following members:
186
187 @table @code
188 @item long int quot
189 The quotient from the division.
190
191 @item long int rem
192 The remainder from the division.
193 @end table
194
195 (This is identical to @code{div_t} except that the components are of
196 type @code{long int} rather than @code{int}.)
197 @end deftp
198
199 @comment stdlib.h
200 @comment ISO
201 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
202 The @code{ldiv} function is similar to @code{div}, except that the
203 arguments are of type @code{long int} and the result is returned as a
204 structure of type @code{ldiv_t}.
205 @end deftypefun
206
207 @comment stdlib.h
208 @comment ISO
209 @deftp {Data Type} lldiv_t
210 This is a structure type used to hold the result returned by the @code{lldiv}
211 function.  It has the following members:
212
213 @table @code
214 @item long long int quot
215 The quotient from the division.
216
217 @item long long int rem
218 The remainder from the division.
219 @end table
220
221 (This is identical to @code{div_t} except that the components are of
222 type @code{long long int} rather than @code{int}.)
223 @end deftp
224
225 @comment stdlib.h
226 @comment ISO
227 @deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator})
228 The @code{lldiv} function is like the @code{div} function, but the
229 arguments are of type @code{long long int} and the result is returned as
230 a structure of type @code{lldiv_t}.
231
232 The @code{lldiv} function was added in @w{ISO C99}.
233 @end deftypefun
234
235 @comment inttypes.h
236 @comment ISO
237 @deftp {Data Type} imaxdiv_t
238 This is a structure type used to hold the result returned by the @code{imaxdiv}
239 function.  It has the following members:
240
241 @table @code
242 @item intmax_t quot
243 The quotient from the division.
244
245 @item intmax_t rem
246 The remainder from the division.
247 @end table
248
249 (This is identical to @code{div_t} except that the components are of
250 type @code{intmax_t} rather than @code{int}.)
251
252 See @ref{Integers} for a description of the @code{intmax_t} type.
253
254 @end deftp
255
256 @comment inttypes.h
257 @comment ISO
258 @deftypefun imaxdiv_t imaxdiv (intmax_t @var{numerator}, intmax_t @var{denominator})
259 The @code{imaxdiv} function is like the @code{div} function, but the
260 arguments are of type @code{intmax_t} and the result is returned as
261 a structure of type @code{imaxdiv_t}.
262
263 See @ref{Integers} for a description of the @code{intmax_t} type.
264
265 The @code{imaxdiv} function was added in @w{ISO C99}.
266 @end deftypefun
267
268
269 @node Floating Point Numbers
270 @section Floating Point Numbers
271 @cindex floating point
272 @cindex IEEE 754
273 @cindex IEEE floating point
274
275 Most computer hardware has support for two different kinds of numbers:
276 integers (@math{@dots{}-3, -2, -1, 0, 1, 2, 3@dots{}}) and
277 floating-point numbers.  Floating-point numbers have three parts: the
278 @dfn{mantissa}, the @dfn{exponent}, and the @dfn{sign bit}.  The real
279 number represented by a floating-point value is given by
280 @tex
281 $(s \mathrel? -1 \mathrel: 1) \cdot 2^e \cdot M$
282 @end tex
283 @ifnottex
284 @math{(s ? -1 : 1) @mul{} 2^e @mul{} M}
285 @end ifnottex
286 where @math{s} is the sign bit, @math{e} the exponent, and @math{M}
287 the mantissa.  @xref{Floating Point Concepts}, for details.  (It is
288 possible to have a different @dfn{base} for the exponent, but all modern
289 hardware uses @math{2}.)
290
291 Floating-point numbers can represent a finite subset of the real
292 numbers.  While this subset is large enough for most purposes, it is
293 important to remember that the only reals that can be represented
294 exactly are rational numbers that have a terminating binary expansion
295 shorter than the width of the mantissa.  Even simple fractions such as
296 @math{1/5} can only be approximated by floating point.
297
298 Mathematical operations and functions frequently need to produce values
299 that are not representable.  Often these values can be approximated
300 closely enough for practical purposes, but sometimes they can't.
301 Historically there was no way to tell when the results of a calculation
302 were inaccurate.  Modern computers implement the @w{IEEE 754} standard
303 for numerical computations, which defines a framework for indicating to
304 the program when the results of calculation are not trustworthy.  This
305 framework consists of a set of @dfn{exceptions} that indicate why a
306 result could not be represented, and the special values @dfn{infinity}
307 and @dfn{not a number} (NaN).
308
309 @node Floating Point Classes
310 @section Floating-Point Number Classification Functions
311 @cindex floating-point classes
312 @cindex classes, floating-point
313 @pindex math.h
314
315 @w{ISO C99} defines macros that let you determine what sort of
316 floating-point number a variable holds.
317
318 @comment math.h
319 @comment ISO
320 @deftypefn {Macro} int fpclassify (@emph{float-type} @var{x})
321 This is a generic macro which works on all floating-point types and
322 which returns a value of type @code{int}.  The possible values are:
323
324 @vtable @code
325 @item FP_NAN
326 The floating-point number @var{x} is ``Not a Number'' (@pxref{Infinity
327 and NaN})
328 @item FP_INFINITE
329 The value of @var{x} is either plus or minus infinity (@pxref{Infinity
330 and NaN})
331 @item FP_ZERO
332 The value of @var{x} is zero.  In floating-point formats like @w{IEEE
333 754}, where zero can be signed, this value is also returned if
334 @var{x} is negative zero.
335 @item FP_SUBNORMAL
336 Numbers whose absolute value is too small to be represented in the
337 normal format are represented in an alternate, @dfn{denormalized} format
338 (@pxref{Floating Point Concepts}).  This format is less precise but can
339 represent values closer to zero.  @code{fpclassify} returns this value
340 for values of @var{x} in this alternate format.
341 @item FP_NORMAL
342 This value is returned for all other values of @var{x}.  It indicates
343 that there is nothing special about the number.
344 @end vtable
345
346 @end deftypefn
347
348 @code{fpclassify} is most useful if more than one property of a number
349 must be tested.  There are more specific macros which only test one
350 property at a time.  Generally these macros execute faster than
351 @code{fpclassify}, since there is special hardware support for them.
352 You should therefore use the specific macros whenever possible.
353
354 @comment math.h
355 @comment ISO
356 @deftypefn {Macro} int isfinite (@emph{float-type} @var{x})
357 This macro returns a nonzero value if @var{x} is finite: not plus or
358 minus infinity, and not NaN.  It is equivalent to
359
360 @smallexample
361 (fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)
362 @end smallexample
363
364 @code{isfinite} is implemented as a macro which accepts any
365 floating-point type.
366 @end deftypefn
367
368 @comment math.h
369 @comment ISO
370 @deftypefn {Macro} int isnormal (@emph{float-type} @var{x})
371 This macro returns a nonzero value if @var{x} is finite and normalized.
372 It is equivalent to
373
374 @smallexample
375 (fpclassify (x) == FP_NORMAL)
376 @end smallexample
377 @end deftypefn
378
379 @comment math.h
380 @comment ISO
381 @deftypefn {Macro} int isnan (@emph{float-type} @var{x})
382 This macro returns a nonzero value if @var{x} is NaN.  It is equivalent
383 to
384
385 @smallexample
386 (fpclassify (x) == FP_NAN)
387 @end smallexample
388 @end deftypefn
389
390 Another set of floating-point classification functions was provided by
391 BSD.  The GNU C library also supports these functions; however, we
392 recommend that you use the ISO C99 macros in new code.  Those are standard
393 and will be available more widely.  Also, since they are macros, you do
394 not have to worry about the type of their argument.
395
396 @comment math.h
397 @comment BSD
398 @deftypefun int isinf (double @var{x})
399 @comment math.h
400 @comment BSD
401 @deftypefunx int isinff (float @var{x})
402 @comment math.h
403 @comment BSD
404 @deftypefunx int isinfl (long double @var{x})
405 This function returns @code{-1} if @var{x} represents negative infinity,
406 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
407 @end deftypefun
408
409 @comment math.h
410 @comment BSD
411 @deftypefun int isnan (double @var{x})
412 @comment math.h
413 @comment BSD
414 @deftypefunx int isnanf (float @var{x})
415 @comment math.h
416 @comment BSD
417 @deftypefunx int isnanl (long double @var{x})
418 This function returns a nonzero value if @var{x} is a ``not a number''
419 value, and zero otherwise.
420
421 @strong{Note:} The @code{isnan} macro defined by @w{ISO C99} overrides
422 the BSD function.  This is normally not a problem, because the two
423 routines behave identically.  However, if you really need to get the BSD
424 function for some reason, you can write
425
426 @smallexample
427 (isnan) (x)
428 @end smallexample
429 @end deftypefun
430
431 @comment math.h
432 @comment BSD
433 @deftypefun int finite (double @var{x})
434 @comment math.h
435 @comment BSD
436 @deftypefunx int finitef (float @var{x})
437 @comment math.h
438 @comment BSD
439 @deftypefunx int finitel (long double @var{x})
440 This function returns a nonzero value if @var{x} is finite or a ``not a
441 number'' value, and zero otherwise.
442 @end deftypefun
443
444 @strong{Portability Note:} The functions listed in this section are BSD
445 extensions.
446
447
448 @node Floating Point Errors
449 @section Errors in Floating-Point Calculations
450
451 @menu
452 * FP Exceptions::               IEEE 754 math exceptions and how to detect them.
453 * Infinity and NaN::            Special values returned by calculations.
454 * Status bit operations::       Checking for exceptions after the fact.
455 * Math Error Reporting::        How the math functions report errors.
456 @end menu
457
458 @node FP Exceptions
459 @subsection FP Exceptions
460 @cindex exception
461 @cindex signal
462 @cindex zero divide
463 @cindex division by zero
464 @cindex inexact exception
465 @cindex invalid exception
466 @cindex overflow exception
467 @cindex underflow exception
468
469 The @w{IEEE 754} standard defines five @dfn{exceptions} that can occur
470 during a calculation.  Each corresponds to a particular sort of error,
471 such as overflow.
472
473 When exceptions occur (when exceptions are @dfn{raised}, in the language
474 of the standard), one of two things can happen.  By default the
475 exception is simply noted in the floating-point @dfn{status word}, and
476 the program continues as if nothing had happened.  The operation
477 produces a default value, which depends on the exception (see the table
478 below).  Your program can check the status word to find out which
479 exceptions happened.
480
481 Alternatively, you can enable @dfn{traps} for exceptions.  In that case,
482 when an exception is raised, your program will receive the @code{SIGFPE}
483 signal.  The default action for this signal is to terminate the
484 program.  @xref{Signal Handling}, for how you can change the effect of
485 the signal.
486
487 @findex matherr
488 In the System V math library, the user-defined function @code{matherr}
489 is called when certain exceptions occur inside math library functions.
490 However, the Unix98 standard deprecates this interface.  We support it
491 for historical compatibility, but recommend that you do not use it in
492 new programs.
493
494 @noindent
495 The exceptions defined in @w{IEEE 754} are:
496
497 @table @samp
498 @item Invalid Operation
499 This exception is raised if the given operands are invalid for the
500 operation to be performed.  Examples are
501 (see @w{IEEE 754}, @w{section 7}):
502 @enumerate
503 @item
504 Addition or subtraction: @math{@infinity{} - @infinity{}}.  (But
505 @math{@infinity{} + @infinity{} = @infinity{}}).
506 @item
507 Multiplication: @math{0 @mul{} @infinity{}}.
508 @item
509 Division: @math{0/0} or @math{@infinity{}/@infinity{}}.
510 @item
511 Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is
512 infinite.
513 @item
514 Square root if the operand is less then zero.  More generally, any
515 mathematical function evaluated outside its domain produces this
516 exception.
517 @item
518 Conversion of a floating-point number to an integer or decimal
519 string, when the number cannot be represented in the target format (due
520 to overflow, infinity, or NaN).
521 @item
522 Conversion of an unrecognizable input string.
523 @item
524 Comparison via predicates involving @math{<} or @math{>}, when one or
525 other of the operands is NaN.  You can prevent this exception by using
526 the unordered comparison functions instead; see @ref{FP Comparison Functions}.
527 @end enumerate
528
529 If the exception does not trap, the result of the operation is NaN.
530
531 @item Division by Zero
532 This exception is raised when a finite nonzero number is divided
533 by zero.  If no trap occurs the result is either @math{+@infinity{}} or
534 @math{-@infinity{}}, depending on the signs of the operands.
535
536 @item Overflow
537 This exception is raised whenever the result cannot be represented
538 as a finite value in the precision format of the destination.  If no trap
539 occurs the result depends on the sign of the intermediate result and the
540 current rounding mode (@w{IEEE 754}, @w{section 7.3}):
541 @enumerate
542 @item
543 Round to nearest carries all overflows to @math{@infinity{}}
544 with the sign of the intermediate result.
545 @item
546 Round toward @math{0} carries all overflows to the largest representable
547 finite number with the sign of the intermediate result.
548 @item
549 Round toward @math{-@infinity{}} carries positive overflows to the
550 largest representable finite number and negative overflows to
551 @math{-@infinity{}}.
552
553 @item
554 Round toward @math{@infinity{}} carries negative overflows to the
555 most negative representable finite number and positive overflows
556 to @math{@infinity{}}.
557 @end enumerate
558
559 Whenever the overflow exception is raised, the inexact exception is also
560 raised.
561
562 @item Underflow
563 The underflow exception is raised when an intermediate result is too
564 small to be calculated accurately, or if the operation's result rounded
565 to the destination precision is too small to be normalized.
566
567 When no trap is installed for the underflow exception, underflow is
568 signaled (via the underflow flag) only when both tininess and loss of
569 accuracy have been detected.  If no trap handler is installed the
570 operation continues with an imprecise small value, or zero if the
571 destination precision cannot hold the small exact result.
572
573 @item Inexact
574 This exception is signalled if a rounded result is not exact (such as
575 when calculating the square root of two) or a result overflows without
576 an overflow trap.
577 @end table
578
579 @node Infinity and NaN
580 @subsection Infinity and NaN
581 @cindex infinity
582 @cindex not a number
583 @cindex NaN
584
585 @w{IEEE 754} floating point numbers can represent positive or negative
586 infinity, and @dfn{NaN} (not a number).  These three values arise from
587 calculations whose result is undefined or cannot be represented
588 accurately.  You can also deliberately set a floating-point variable to
589 any of them, which is sometimes useful.  Some examples of calculations
590 that produce infinity or NaN:
591
592 @ifnottex
593 @smallexample
594 @math{1/0 = @infinity{}}
595 @math{log (0) = -@infinity{}}
596 @math{sqrt (-1) = NaN}
597 @end smallexample
598 @end ifnottex
599 @tex
600 $${1\over0} = \infty$$
601 $$\log 0 = -\infty$$
602 $$\sqrt{-1} = \hbox{NaN}$$
603 @end tex
604
605 When a calculation produces any of these values, an exception also
606 occurs; see @ref{FP Exceptions}.
607
608 The basic operations and math functions all accept infinity and NaN and
609 produce sensible output.  Infinities propagate through calculations as
610 one would expect: for example, @math{2 + @infinity{} = @infinity{}},
611 @math{4/@infinity{} = 0}, atan @math{(@infinity{}) = @pi{}/2}.  NaN, on
612 the other hand, infects any calculation that involves it.  Unless the
613 calculation would produce the same result no matter what real value
614 replaced NaN, the result is NaN.
615
616 In comparison operations, positive infinity is larger than all values
617 except itself and NaN, and negative infinity is smaller than all values
618 except itself and NaN.  NaN is @dfn{unordered}: it is not equal to,
619 greater than, or less than anything, @emph{including itself}. @code{x ==
620 x} is false if the value of @code{x} is NaN.  You can use this to test
621 whether a value is NaN or not, but the recommended way to test for NaN
622 is with the @code{isnan} function (@pxref{Floating Point Classes}).  In
623 addition, @code{<}, @code{>}, @code{<=}, and @code{>=} will raise an
624 exception when applied to NaNs.
625
626 @file{math.h} defines macros that allow you to explicitly set a variable
627 to infinity or NaN.
628
629 @comment math.h
630 @comment ISO
631 @deftypevr Macro float INFINITY
632 An expression representing positive infinity.  It is equal to the value
633 produced  by mathematical operations like @code{1.0 / 0.0}.
634 @code{-INFINITY} represents negative infinity.
635
636 You can test whether a floating-point value is infinite by comparing it
637 to this macro.  However, this is not recommended; you should use the
638 @code{isfinite} macro instead.  @xref{Floating Point Classes}.
639
640 This macro was introduced in the @w{ISO C99} standard.
641 @end deftypevr
642
643 @comment math.h
644 @comment GNU
645 @deftypevr Macro float NAN
646 An expression representing a value which is ``not a number''.  This
647 macro is a GNU extension, available only on machines that support the
648 ``not a number'' value---that is to say, on all machines that support
649 IEEE floating point.
650
651 You can use @samp{#ifdef NAN} to test whether the machine supports
652 NaN.  (Of course, you must arrange for GNU extensions to be visible,
653 such as by defining @code{_GNU_SOURCE}, and then you must include
654 @file{math.h}.)
655 @end deftypevr
656
657 @w{IEEE 754} also allows for another unusual value: negative zero.  This
658 value is produced when you divide a positive number by negative
659 infinity, or when a negative result is smaller than the limits of
660 representation.  Negative zero behaves identically to zero in all
661 calculations, unless you explicitly test the sign bit with
662 @code{signbit} or @code{copysign}.
663
664 @node Status bit operations
665 @subsection Examining the FPU status word
666
667 @w{ISO C99} defines functions to query and manipulate the
668 floating-point status word.  You can use these functions to check for
669 untrapped exceptions when it's convenient, rather than worrying about
670 them in the middle of a calculation.
671
672 These constants represent the various @w{IEEE 754} exceptions.  Not all
673 FPUs report all the different exceptions.  Each constant is defined if
674 and only if the FPU you are compiling for supports that exception, so
675 you can test for FPU support with @samp{#ifdef}.  They are defined in
676 @file{fenv.h}.
677
678 @vtable @code
679 @comment fenv.h
680 @comment ISO
681 @item FE_INEXACT
682  The inexact exception.
683 @comment fenv.h
684 @comment ISO
685 @item FE_DIVBYZERO
686  The divide by zero exception.
687 @comment fenv.h
688 @comment ISO
689 @item FE_UNDERFLOW
690  The underflow exception.
691 @comment fenv.h
692 @comment ISO
693 @item FE_OVERFLOW
694  The overflow exception.
695 @comment fenv.h
696 @comment ISO
697 @item FE_INVALID
698  The invalid exception.
699 @end vtable
700
701 The macro @code{FE_ALL_EXCEPT} is the bitwise OR of all exception macros
702 which are supported by the FP implementation.
703
704 These functions allow you to clear exception flags, test for exceptions,
705 and save and restore the set of exceptions flagged.
706
707 @comment fenv.h
708 @comment ISO
709 @deftypefun int feclearexcept (int @var{excepts})
710 This function clears all of the supported exception flags indicated by
711 @var{excepts}.
712
713 The function returns zero in case the operation was successful, a
714 non-zero value otherwise.
715 @end deftypefun
716
717 @comment fenv.h
718 @comment ISO
719 @deftypefun int feraiseexcept (int @var{excepts})
720 This function raises the supported exceptions indicated by
721 @var{excepts}.  If more than one exception bit in @var{excepts} is set
722 the order in which the exceptions are raised is undefined except that
723 overflow (@code{FE_OVERFLOW}) or underflow (@code{FE_UNDERFLOW}) are
724 raised before inexact (@code{FE_INEXACT}).  Whether for overflow or
725 underflow the inexact exception is also raised is also implementation
726 dependent.
727
728 The function returns zero in case the operation was successful, a
729 non-zero value otherwise.
730 @end deftypefun
731
732 @comment fenv.h
733 @comment ISO
734 @deftypefun int fetestexcept (int @var{excepts})
735 Test whether the exception flags indicated by the parameter @var{except}
736 are currently set.  If any of them are, a nonzero value is returned
737 which specifies which exceptions are set.  Otherwise the result is zero.
738 @end deftypefun
739
740 To understand these functions, imagine that the status word is an
741 integer variable named @var{status}.  @code{feclearexcept} is then
742 equivalent to @samp{status &= ~excepts} and @code{fetestexcept} is
743 equivalent to @samp{(status & excepts)}.  The actual implementation may
744 be very different, of course.
745
746 Exception flags are only cleared when the program explicitly requests it,
747 by calling @code{feclearexcept}.  If you want to check for exceptions
748 from a set of calculations, you should clear all the flags first.  Here
749 is a simple example of the way to use @code{fetestexcept}:
750
751 @smallexample
752 @{
753   double f;
754   int raised;
755   feclearexcept (FE_ALL_EXCEPT);
756   f = compute ();
757   raised = fetestexcept (FE_OVERFLOW | FE_INVALID);
758   if (raised & FE_OVERFLOW) @{ /* @dots{} */ @}
759   if (raised & FE_INVALID) @{ /* @dots{} */ @}
760   /* @dots{} */
761 @}
762 @end smallexample
763
764 You cannot explicitly set bits in the status word.  You can, however,
765 save the entire status word and restore it later.  This is done with the
766 following functions:
767
768 @comment fenv.h
769 @comment ISO
770 @deftypefun int fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts})
771 This function stores in the variable pointed to by @var{flagp} an
772 implementation-defined value representing the current setting of the
773 exception flags indicated by @var{excepts}.
774
775 The function returns zero in case the operation was successful, a
776 non-zero value otherwise.
777 @end deftypefun
778
779 @comment fenv.h
780 @comment ISO
781 @deftypefun int fesetexceptflag (const fexcept_t *@var{flagp}, int
782 @var{excepts})
783 This function restores the flags for the exceptions indicated by
784 @var{excepts} to the values stored in the variable pointed to by
785 @var{flagp}.
786
787 The function returns zero in case the operation was successful, a
788 non-zero value otherwise.
789 @end deftypefun
790
791 Note that the value stored in @code{fexcept_t} bears no resemblance to
792 the bit mask returned by @code{fetestexcept}.  The type may not even be
793 an integer.  Do not attempt to modify an @code{fexcept_t} variable.
794
795 @node Math Error Reporting
796 @subsection Error Reporting by Mathematical Functions
797 @cindex errors, mathematical
798 @cindex domain error
799 @cindex range error
800
801 Many of the math functions are defined only over a subset of the real or
802 complex numbers.  Even if they are mathematically defined, their result
803 may be larger or smaller than the range representable by their return
804 type.  These are known as @dfn{domain errors}, @dfn{overflows}, and
805 @dfn{underflows}, respectively.  Math functions do several things when
806 one of these errors occurs.  In this manual we will refer to the
807 complete response as @dfn{signalling} a domain error, overflow, or
808 underflow.
809
810 When a math function suffers a domain error, it raises the invalid
811 exception and returns NaN.  It also sets @var{errno} to @code{EDOM};
812 this is for compatibility with old systems that do not support @w{IEEE
813 754} exception handling.  Likewise, when overflow occurs, math
814 functions raise the overflow exception and return @math{@infinity{}} or
815 @math{-@infinity{}} as appropriate.  They also set @var{errno} to
816 @code{ERANGE}.  When underflow occurs, the underflow exception is
817 raised, and zero (appropriately signed) is returned.  @var{errno} may be
818 set to @code{ERANGE}, but this is not guaranteed.
819
820 Some of the math functions are defined mathematically to result in a
821 complex value over parts of their domains.  The most familiar example of
822 this is taking the square root of a negative number.  The complex math
823 functions, such as @code{csqrt}, will return the appropriate complex value
824 in this case.  The real-valued functions, such as @code{sqrt}, will
825 signal a domain error.
826
827 Some older hardware does not support infinities.  On that hardware,
828 overflows instead return a particular very large number (usually the
829 largest representable number).  @file{math.h} defines macros you can use
830 to test for overflow on both old and new hardware.
831
832 @comment math.h
833 @comment ISO
834 @deftypevr Macro double HUGE_VAL
835 @comment math.h
836 @comment ISO
837 @deftypevrx Macro float HUGE_VALF
838 @comment math.h
839 @comment ISO
840 @deftypevrx Macro {long double} HUGE_VALL
841 An expression representing a particular very large number.  On machines
842 that use @w{IEEE 754} floating point format, @code{HUGE_VAL} is infinity.
843 On other machines, it's typically the largest positive number that can
844 be represented.
845
846 Mathematical functions return the appropriately typed version of
847 @code{HUGE_VAL} or @code{@minus{}HUGE_VAL} when the result is too large
848 to be represented.
849 @end deftypevr
850
851 @node Rounding
852 @section Rounding Modes
853
854 Floating-point calculations are carried out internally with extra
855 precision, and then rounded to fit into the destination type.  This
856 ensures that results are as precise as the input data.  @w{IEEE 754}
857 defines four possible rounding modes:
858
859 @table @asis
860 @item Round to nearest.
861 This is the default mode.  It should be used unless there is a specific
862 need for one of the others.  In this mode results are rounded to the
863 nearest representable value.  If the result is midway between two
864 representable values, the even representable is chosen. @dfn{Even} here
865 means the lowest-order bit is zero.  This rounding mode prevents
866 statistical bias and guarantees numeric stability: round-off errors in a
867 lengthy calculation will remain smaller than half of @code{FLT_EPSILON}.
868
869 @c @item Round toward @math{+@infinity{}}
870 @item Round toward plus Infinity.
871 All results are rounded to the smallest representable value
872 which is greater than the result.
873
874 @c @item Round toward @math{-@infinity{}}
875 @item Round toward minus Infinity.
876 All results are rounded to the largest representable value which is less
877 than the result.
878
879 @item Round toward zero.
880 All results are rounded to the largest representable value whose
881 magnitude is less than that of the result.  In other words, if the
882 result is negative it is rounded up; if it is positive, it is rounded
883 down.
884 @end table
885
886 @noindent
887 @file{fenv.h} defines constants which you can use to refer to the
888 various rounding modes.  Each one will be defined if and only if the FPU
889 supports the corresponding rounding mode.
890
891 @table @code
892 @comment fenv.h
893 @comment ISO
894 @vindex FE_TONEAREST
895 @item FE_TONEAREST
896 Round to nearest.
897
898 @comment fenv.h
899 @comment ISO
900 @vindex FE_UPWARD
901 @item FE_UPWARD
902 Round toward @math{+@infinity{}}.
903
904 @comment fenv.h
905 @comment ISO
906 @vindex FE_DOWNWARD
907 @item FE_DOWNWARD
908 Round toward @math{-@infinity{}}.
909
910 @comment fenv.h
911 @comment ISO
912 @vindex FE_TOWARDZERO
913 @item FE_TOWARDZERO
914 Round toward zero.
915 @end table
916
917 Underflow is an unusual case.  Normally, @w{IEEE 754} floating point
918 numbers are always normalized (@pxref{Floating Point Concepts}).
919 Numbers smaller than @math{2^r} (where @math{r} is the minimum exponent,
920 @code{FLT_MIN_RADIX-1} for @var{float}) cannot be represented as
921 normalized numbers.  Rounding all such numbers to zero or @math{2^r}
922 would cause some algorithms to fail at 0.  Therefore, they are left in
923 denormalized form.  That produces loss of precision, since some bits of
924 the mantissa are stolen to indicate the decimal point.
925
926 If a result is too small to be represented as a denormalized number, it
927 is rounded to zero.  However, the sign of the result is preserved; if
928 the calculation was negative, the result is @dfn{negative zero}.
929 Negative zero can also result from some operations on infinity, such as
930 @math{4/-@infinity{}}.  Negative zero behaves identically to zero except
931 when the @code{copysign} or @code{signbit} functions are used to check
932 the sign bit directly.
933
934 At any time one of the above four rounding modes is selected.  You can
935 find out which one with this function:
936
937 @comment fenv.h
938 @comment ISO
939 @deftypefun int fegetround (void)
940 Returns the currently selected rounding mode, represented by one of the
941 values of the defined rounding mode macros.
942 @end deftypefun
943
944 @noindent
945 To change the rounding mode, use this function:
946
947 @comment fenv.h
948 @comment ISO
949 @deftypefun int fesetround (int @var{round})
950 Changes the currently selected rounding mode to @var{round}.  If
951 @var{round} does not correspond to one of the supported rounding modes
952 nothing is changed.  @code{fesetround} returns zero if it changed the
953 rounding mode, a nonzero value if the mode is not supported.
954 @end deftypefun
955
956 You should avoid changing the rounding mode if possible.  It can be an
957 expensive operation; also, some hardware requires you to compile your
958 program differently for it to work.  The resulting code may run slower.
959 See your compiler documentation for details.
960 @c This section used to claim that functions existed to round one number
961 @c in a specific fashion.  I can't find any functions in the library
962 @c that do that. -zw
963
964 @node Control Functions
965 @section Floating-Point Control Functions
966
967 @w{IEEE 754} floating-point implementations allow the programmer to
968 decide whether traps will occur for each of the exceptions, by setting
969 bits in the @dfn{control word}.  In C, traps result in the program
970 receiving the @code{SIGFPE} signal; see @ref{Signal Handling}.
971
972 @strong{Note:} @w{IEEE 754} says that trap handlers are given details of
973 the exceptional situation, and can set the result value.  C signals do
974 not provide any mechanism to pass this information back and forth.
975 Trapping exceptions in C is therefore not very useful.
976
977 It is sometimes necessary to save the state of the floating-point unit
978 while you perform some calculation.  The library provides functions
979 which save and restore the exception flags, the set of exceptions that
980 generate traps, and the rounding mode.  This information is known as the
981 @dfn{floating-point environment}.
982
983 The functions to save and restore the floating-point environment all use
984 a variable of type @code{fenv_t} to store information.  This type is
985 defined in @file{fenv.h}.  Its size and contents are
986 implementation-defined.  You should not attempt to manipulate a variable
987 of this type directly.
988
989 To save the state of the FPU, use one of these functions:
990
991 @comment fenv.h
992 @comment ISO
993 @deftypefun int fegetenv (fenv_t *@var{envp})
994 Store the floating-point environment in the variable pointed to by
995 @var{envp}.
996
997 The function returns zero in case the operation was successful, a
998 non-zero value otherwise.
999 @end deftypefun
1000
1001 @comment fenv.h
1002 @comment ISO
1003 @deftypefun int feholdexcept (fenv_t *@var{envp})
1004 Store the current floating-point environment in the object pointed to by
1005 @var{envp}.  Then clear all exception flags, and set the FPU to trap no
1006 exceptions.  Not all FPUs support trapping no exceptions; if
1007 @code{feholdexcept} cannot set this mode, it returns nonzero value.  If it
1008 succeeds, it returns zero.
1009 @end deftypefun
1010
1011 The functions which restore the floating-point environment can take these
1012 kinds of arguments:
1013
1014 @itemize @bullet
1015 @item
1016 Pointers to @code{fenv_t} objects, which were initialized previously by a
1017 call to @code{fegetenv} or @code{feholdexcept}.
1018 @item
1019 @vindex FE_DFL_ENV
1020 The special macro @code{FE_DFL_ENV} which represents the floating-point
1021 environment as it was available at program start.
1022 @item
1023 Implementation defined macros with names starting with @code{FE_} and
1024 having type @code{fenv_t *}.
1025
1026 @vindex FE_NOMASK_ENV
1027 If possible, the GNU C Library defines a macro @code{FE_NOMASK_ENV}
1028 which represents an environment where every exception raised causes a
1029 trap to occur.  You can test for this macro using @code{#ifdef}.  It is
1030 only defined if @code{_GNU_SOURCE} is defined.
1031
1032 Some platforms might define other predefined environments.
1033 @end itemize
1034
1035 @noindent
1036 To set the floating-point environment, you can use either of these
1037 functions:
1038
1039 @comment fenv.h
1040 @comment ISO
1041 @deftypefun int fesetenv (const fenv_t *@var{envp})
1042 Set the floating-point environment to that described by @var{envp}.
1043
1044 The function returns zero in case the operation was successful, a
1045 non-zero value otherwise.
1046 @end deftypefun
1047
1048 @comment fenv.h
1049 @comment ISO
1050 @deftypefun int feupdateenv (const fenv_t *@var{envp})
1051 Like @code{fesetenv}, this function sets the floating-point environment
1052 to that described by @var{envp}.  However, if any exceptions were
1053 flagged in the status word before @code{feupdateenv} was called, they
1054 remain flagged after the call.  In other words, after @code{feupdateenv}
1055 is called, the status word is the bitwise OR of the previous status word
1056 and the one saved in @var{envp}.
1057
1058 The function returns zero in case the operation was successful, a
1059 non-zero value otherwise.
1060 @end deftypefun
1061
1062 @noindent
1063 To control for individual exceptions if raising them causes a trap to
1064 occur, you can use the following two functions.
1065
1066 @strong{Portability Note:} These functions are all GNU extensions.
1067
1068 @comment fenv.h
1069 @comment GNU
1070 @deftypefun int feenableexcept (int @var{excepts})
1071 This functions enables traps for each of the exceptions as indicated by
1072 the parameter @var{except}.  The individual excepetions are described in
1073 @ref{Status bit operations}.  Only the specified exceptions are
1074 enabled, the status of the other exceptions is not changed.
1075
1076 The function returns the previous enabled exceptions in case the
1077 operation was successful, @code{-1} otherwise.
1078 @end deftypefun
1079
1080 @comment fenv.h
1081 @comment GNU
1082 @deftypefun int fedisableexcept (int @var{excepts})
1083 This functions disables traps for each of the exceptions as indicated by
1084 the parameter @var{except}.  The individual excepetions are described in
1085 @ref{Status bit operations}.  Only the specified exceptions are
1086 disabled, the status of the other exceptions is not changed.
1087
1088 The function returns the previous enabled exceptions in case the
1089 operation was successful, @code{-1} otherwise.
1090 @end deftypefun
1091
1092 @comment fenv.h
1093 @comment GNU
1094 @deftypefun int fegetexcept (int @var{excepts})
1095 The function returns a bitmask of all currently enabled exceptions.  It
1096 returns @code{-1} in case of failure.
1097 @end deftypefun
1098
1099 @node Arithmetic Functions
1100 @section Arithmetic Functions
1101
1102 The C library provides functions to do basic operations on
1103 floating-point numbers.  These include absolute value, maximum and minimum,
1104 normalization, bit twiddling, rounding, and a few others.
1105
1106 @menu
1107 * Absolute Value::              Absolute values of integers and floats.
1108 * Normalization Functions::     Extracting exponents and putting them back.
1109 * Rounding Functions::          Rounding floats to integers.
1110 * Remainder Functions::         Remainders on division, precisely defined.
1111 * FP Bit Twiddling::            Sign bit adjustment.  Adding epsilon.
1112 * FP Comparison Functions::     Comparisons without risk of exceptions.
1113 * Misc FP Arithmetic::          Max, min, positive difference, multiply-add.
1114 @end menu
1115
1116 @node Absolute Value
1117 @subsection Absolute Value
1118 @cindex absolute value functions
1119
1120 These functions are provided for obtaining the @dfn{absolute value} (or
1121 @dfn{magnitude}) of a number.  The absolute value of a real number
1122 @var{x} is @var{x} if @var{x} is positive, @minus{}@var{x} if @var{x} is
1123 negative.  For a complex number @var{z}, whose real part is @var{x} and
1124 whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt
1125 (@var{x}*@var{x} + @var{y}*@var{y})}}.
1126
1127 @pindex math.h
1128 @pindex stdlib.h
1129 Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h};
1130 @code{imaxabs} is declared in @file{inttypes.h};
1131 @code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h}.
1132 @code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}.
1133
1134 @comment stdlib.h
1135 @comment ISO
1136 @deftypefun int abs (int @var{number})
1137 @comment stdlib.h
1138 @comment ISO
1139 @deftypefunx {long int} labs (long int @var{number})
1140 @comment stdlib.h
1141 @comment ISO
1142 @deftypefunx {long long int} llabs (long long int @var{number})
1143 @comment inttypes.h
1144 @comment ISO
1145 @deftypefunx intmax_t imaxabs (intmax_t @var{number})
1146 These functions return the absolute value of @var{number}.
1147
1148 Most computers use a two's complement integer representation, in which
1149 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
1150 cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined.
1151
1152 @code{llabs} and @code{imaxdiv} are new to @w{ISO C99}.
1153
1154 See @ref{Integers} for a description of the @code{intmax_t} type.
1155
1156 @end deftypefun
1157
1158 @comment math.h
1159 @comment ISO
1160 @deftypefun double fabs (double @var{number})
1161 @comment math.h
1162 @comment ISO
1163 @deftypefunx float fabsf (float @var{number})
1164 @comment math.h
1165 @comment ISO
1166 @deftypefunx {long double} fabsl (long double @var{number})
1167 This function returns the absolute value of the floating-point number
1168 @var{number}.
1169 @end deftypefun
1170
1171 @comment complex.h
1172 @comment ISO
1173 @deftypefun double cabs (complex double @var{z})
1174 @comment complex.h
1175 @comment ISO
1176 @deftypefunx float cabsf (complex float @var{z})
1177 @comment complex.h
1178 @comment ISO
1179 @deftypefunx {long double} cabsl (complex long double @var{z})
1180 These functions return the absolute  value of the complex number @var{z}
1181 (@pxref{Complex Numbers}).  The absolute value of a complex number is:
1182
1183 @smallexample
1184 sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z}))
1185 @end smallexample
1186
1187 This function should always be used instead of the direct formula
1188 because it takes special care to avoid losing precision.  It may also
1189 take advantage of hardware support for this operation. See @code{hypot}
1190 in @ref{Exponents and Logarithms}.
1191 @end deftypefun
1192
1193 @node Normalization Functions
1194 @subsection Normalization Functions
1195 @cindex normalization functions (floating-point)
1196
1197 The functions described in this section are primarily provided as a way
1198 to efficiently perform certain low-level manipulations on floating point
1199 numbers that are represented internally using a binary radix;
1200 see @ref{Floating Point Concepts}.  These functions are required to
1201 have equivalent behavior even if the representation does not use a radix
1202 of 2, but of course they are unlikely to be particularly efficient in
1203 those cases.
1204
1205 @pindex math.h
1206 All these functions are declared in @file{math.h}.
1207
1208 @comment math.h
1209 @comment ISO
1210 @deftypefun double frexp (double @var{value}, int *@var{exponent})
1211 @comment math.h
1212 @comment ISO
1213 @deftypefunx float frexpf (float @var{value}, int *@var{exponent})
1214 @comment math.h
1215 @comment ISO
1216 @deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent})
1217 These functions are used to split the number @var{value}
1218 into a normalized fraction and an exponent.
1219
1220 If the argument @var{value} is not zero, the return value is @var{value}
1221 times a power of two, and is always in the range 1/2 (inclusive) to 1
1222 (exclusive).  The corresponding exponent is stored in
1223 @code{*@var{exponent}}; the return value multiplied by 2 raised to this
1224 exponent equals the original number @var{value}.
1225
1226 For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and
1227 stores @code{4} in @code{exponent}.
1228
1229 If @var{value} is zero, then the return value is zero and
1230 zero is stored in @code{*@var{exponent}}.
1231 @end deftypefun
1232
1233 @comment math.h
1234 @comment ISO
1235 @deftypefun double ldexp (double @var{value}, int @var{exponent})
1236 @comment math.h
1237 @comment ISO
1238 @deftypefunx float ldexpf (float @var{value}, int @var{exponent})
1239 @comment math.h
1240 @comment ISO
1241 @deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent})
1242 These functions return the result of multiplying the floating-point
1243 number @var{value} by 2 raised to the power @var{exponent}.  (It can
1244 be used to reassemble floating-point numbers that were taken apart
1245 by @code{frexp}.)
1246
1247 For example, @code{ldexp (0.8, 4)} returns @code{12.8}.
1248 @end deftypefun
1249
1250 The following functions, which come from BSD, provide facilities
1251 equivalent to those of @code{ldexp} and @code{frexp}.  See also the
1252 @w{ISO C} function @code{logb} which originally also appeared in BSD.
1253
1254 @comment math.h
1255 @comment BSD
1256 @deftypefun double scalb (double @var{value}, int @var{exponent})
1257 @comment math.h
1258 @comment BSD
1259 @deftypefunx float scalbf (float @var{value}, int @var{exponent})
1260 @comment math.h
1261 @comment BSD
1262 @deftypefunx {long double} scalbl (long double @var{value}, int @var{exponent})
1263 The @code{scalb} function is the BSD name for @code{ldexp}.
1264 @end deftypefun
1265
1266 @comment math.h
1267 @comment BSD
1268 @deftypefun {long long int} scalbn (double @var{x}, int n)
1269 @comment math.h
1270 @comment BSD
1271 @deftypefunx {long long int} scalbnf (float @var{x}, int n)
1272 @comment math.h
1273 @comment BSD
1274 @deftypefunx {long long int} scalbnl (long double @var{x}, int n)
1275 @code{scalbn} is identical to @code{scalb}, except that the exponent
1276 @var{n} is an @code{int} instead of a floating-point number.
1277 @end deftypefun
1278
1279 @comment math.h
1280 @comment BSD
1281 @deftypefun {long long int} scalbln (double @var{x}, long int n)
1282 @comment math.h
1283 @comment BSD
1284 @deftypefunx {long long int} scalblnf (float @var{x}, long int n)
1285 @comment math.h
1286 @comment BSD
1287 @deftypefunx {long long int} scalblnl (long double @var{x}, long int n)
1288 @code{scalbln} is identical to @code{scalb}, except that the exponent
1289 @var{n} is a @code{long int} instead of a floating-point number.
1290 @end deftypefun
1291
1292 @comment math.h
1293 @comment BSD
1294 @deftypefun {long long int} significand (double @var{x})
1295 @comment math.h
1296 @comment BSD
1297 @deftypefunx {long long int} significandf (float @var{x})
1298 @comment math.h
1299 @comment BSD
1300 @deftypefunx {long long int} significandl (long double @var{x})
1301 @code{significand} returns the mantissa of @var{x} scaled to the range
1302 @math{[1, 2)}.
1303 It is equivalent to @w{@code{scalb (@var{x}, (double) -ilogb (@var{x}))}}.
1304
1305 This function exists mainly for use in certain standardized tests
1306 of @w{IEEE 754} conformance.
1307 @end deftypefun
1308
1309 @node Rounding Functions
1310 @subsection Rounding Functions
1311 @cindex converting floats to integers
1312
1313 @pindex math.h
1314 The functions listed here perform operations such as rounding and
1315 truncation of floating-point values. Some of these functions convert
1316 floating point numbers to integer values.  They are all declared in
1317 @file{math.h}.
1318
1319 You can also convert floating-point numbers to integers simply by
1320 casting them to @code{int}.  This discards the fractional part,
1321 effectively rounding towards zero.  However, this only works if the
1322 result can actually be represented as an @code{int}---for very large
1323 numbers, this is impossible.  The functions listed here return the
1324 result as a @code{double} instead to get around this problem.
1325
1326 @comment math.h
1327 @comment ISO
1328 @deftypefun double ceil (double @var{x})
1329 @comment math.h
1330 @comment ISO
1331 @deftypefunx float ceilf (float @var{x})
1332 @comment math.h
1333 @comment ISO
1334 @deftypefunx {long double} ceill (long double @var{x})
1335 These functions round @var{x} upwards to the nearest integer,
1336 returning that value as a @code{double}.  Thus, @code{ceil (1.5)}
1337 is @code{2.0}.
1338 @end deftypefun
1339
1340 @comment math.h
1341 @comment ISO
1342 @deftypefun double floor (double @var{x})
1343 @comment math.h
1344 @comment ISO
1345 @deftypefunx float floorf (float @var{x})
1346 @comment math.h
1347 @comment ISO
1348 @deftypefunx {long double} floorl (long double @var{x})
1349 These functions round @var{x} downwards to the nearest
1350 integer, returning that value as a @code{double}.  Thus, @code{floor
1351 (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
1352 @end deftypefun
1353
1354 @comment math.h
1355 @comment ISO
1356 @deftypefun double trunc (double @var{x})
1357 @comment math.h
1358 @comment ISO
1359 @deftypefunx float truncf (float @var{x})
1360 @comment math.h
1361 @comment ISO
1362 @deftypefunx {long double} truncl (long double @var{x})
1363 The @code{trunc} functions round @var{x} towards zero to the nearest
1364 integer (returned in floating-point format).  Thus, @code{trunc (1.5)}
1365 is @code{1.0} and @code{trunc (-1.5)} is @code{-1.0}.
1366 @end deftypefun
1367
1368 @comment math.h
1369 @comment ISO
1370 @deftypefun double rint (double @var{x})
1371 @comment math.h
1372 @comment ISO
1373 @deftypefunx float rintf (float @var{x})
1374 @comment math.h
1375 @comment ISO
1376 @deftypefunx {long double} rintl (long double @var{x})
1377 These functions round @var{x} to an integer value according to the
1378 current rounding mode.  @xref{Floating Point Parameters}, for
1379 information about the various rounding modes.  The default
1380 rounding mode is to round to the nearest integer; some machines
1381 support other modes, but round-to-nearest is always used unless
1382 you explicitly select another.
1383
1384 If @var{x} was not initially an integer, these functions raise the
1385 inexact exception.
1386 @end deftypefun
1387
1388 @comment math.h
1389 @comment ISO
1390 @deftypefun double nearbyint (double @var{x})
1391 @comment math.h
1392 @comment ISO
1393 @deftypefunx float nearbyintf (float @var{x})
1394 @comment math.h
1395 @comment ISO
1396 @deftypefunx {long double} nearbyintl (long double @var{x})
1397 These functions return the same value as the @code{rint} functions, but
1398 do not raise the inexact exception if @var{x} is not an integer.
1399 @end deftypefun
1400
1401 @comment math.h
1402 @comment ISO
1403 @deftypefun double round (double @var{x})
1404 @comment math.h
1405 @comment ISO
1406 @deftypefunx float roundf (float @var{x})
1407 @comment math.h
1408 @comment ISO
1409 @deftypefunx {long double} roundl (long double @var{x})
1410 These functions are similar to @code{rint}, but they round halfway
1411 cases away from zero instead of to the nearest even integer.
1412 @end deftypefun
1413
1414 @comment math.h
1415 @comment ISO
1416 @deftypefun {long int} lrint (double @var{x})
1417 @comment math.h
1418 @comment ISO
1419 @deftypefunx {long int} lrintf (float @var{x})
1420 @comment math.h
1421 @comment ISO
1422 @deftypefunx {long int} lrintl (long double @var{x})
1423 These functions are just like @code{rint}, but they return a
1424 @code{long int} instead of a floating-point number.
1425 @end deftypefun
1426
1427 @comment math.h
1428 @comment ISO
1429 @deftypefun {long long int} llrint (double @var{x})
1430 @comment math.h
1431 @comment ISO
1432 @deftypefunx {long long int} llrintf (float @var{x})
1433 @comment math.h
1434 @comment ISO
1435 @deftypefunx {long long int} llrintl (long double @var{x})
1436 These functions are just like @code{rint}, but they return a
1437 @code{long long int} instead of a floating-point number.
1438 @end deftypefun
1439
1440 @comment math.h
1441 @comment ISO
1442 @deftypefun {long int} lround (double @var{x})
1443 @comment math.h
1444 @comment ISO
1445 @deftypefunx {long int} lroundf (float @var{x})
1446 @comment math.h
1447 @comment ISO
1448 @deftypefunx {long int} lroundl (long double @var{x})
1449 These functions are just like @code{round}, but they return a
1450 @code{long int} instead of a floating-point number.
1451 @end deftypefun
1452
1453 @comment math.h
1454 @comment ISO
1455 @deftypefun {long long int} llround (double @var{x})
1456 @comment math.h
1457 @comment ISO
1458 @deftypefunx {long long int} llroundf (float @var{x})
1459 @comment math.h
1460 @comment ISO
1461 @deftypefunx {long long int} llroundl (long double @var{x})
1462 These functions are just like @code{round}, but they return a
1463 @code{long long int} instead of a floating-point number.
1464 @end deftypefun
1465
1466
1467 @comment math.h
1468 @comment ISO
1469 @deftypefun double modf (double @var{value}, double *@var{integer-part})
1470 @comment math.h
1471 @comment ISO
1472 @deftypefunx float modff (float @var{value}, float *@var{integer-part})
1473 @comment math.h
1474 @comment ISO
1475 @deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part})
1476 These functions break the argument @var{value} into an integer part and a
1477 fractional part (between @code{-1} and @code{1}, exclusive).  Their sum
1478 equals @var{value}.  Each of the parts has the same sign as @var{value},
1479 and the integer part is always rounded toward zero.
1480
1481 @code{modf} stores the integer part in @code{*@var{integer-part}}, and
1482 returns the fractional part.  For example, @code{modf (2.5, &intpart)}
1483 returns @code{0.5} and stores @code{2.0} into @code{intpart}.
1484 @end deftypefun
1485
1486 @node Remainder Functions
1487 @subsection Remainder Functions
1488
1489 The functions in this section compute the remainder on division of two
1490 floating-point numbers.  Each is a little different; pick the one that
1491 suits your problem.
1492
1493 @comment math.h
1494 @comment ISO
1495 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
1496 @comment math.h
1497 @comment ISO
1498 @deftypefunx float fmodf (float @var{numerator}, float @var{denominator})
1499 @comment math.h
1500 @comment ISO
1501 @deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator})
1502 These functions compute the remainder from the division of
1503 @var{numerator} by @var{denominator}.  Specifically, the return value is
1504 @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
1505 is the quotient of @var{numerator} divided by @var{denominator}, rounded
1506 towards zero to an integer.  Thus, @w{@code{fmod (6.5, 2.3)}} returns
1507 @code{1.9}, which is @code{6.5} minus @code{4.6}.
1508
1509 The result has the same sign as the @var{numerator} and has magnitude
1510 less than the magnitude of the @var{denominator}.
1511
1512 If @var{denominator} is zero, @code{fmod} signals a domain error.
1513 @end deftypefun
1514
1515 @comment math.h
1516 @comment BSD
1517 @deftypefun double drem (double @var{numerator}, double @var{denominator})
1518 @comment math.h
1519 @comment BSD
1520 @deftypefunx float dremf (float @var{numerator}, float @var{denominator})
1521 @comment math.h
1522 @comment BSD
1523 @deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator})
1524 These functions are like @code{fmod} except that they rounds the
1525 internal quotient @var{n} to the nearest integer instead of towards zero
1526 to an integer.  For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
1527 which is @code{6.5} minus @code{6.9}.
1528
1529 The absolute value of the result is less than or equal to half the
1530 absolute value of the @var{denominator}.  The difference between
1531 @code{fmod (@var{numerator}, @var{denominator})} and @code{drem
1532 (@var{numerator}, @var{denominator})} is always either
1533 @var{denominator}, minus @var{denominator}, or zero.
1534
1535 If @var{denominator} is zero, @code{drem} signals a domain error.
1536 @end deftypefun
1537
1538 @comment math.h
1539 @comment BSD
1540 @deftypefun double remainder (double @var{numerator}, double @var{denominator})
1541 @comment math.h
1542 @comment BSD
1543 @deftypefunx float remainderf (float @var{numerator}, float @var{denominator})
1544 @comment math.h
1545 @comment BSD
1546 @deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator})
1547 This function is another name for @code{drem}.
1548 @end deftypefun
1549
1550 @node FP Bit Twiddling
1551 @subsection Setting and modifying single bits of FP values
1552 @cindex FP arithmetic
1553
1554 There are some operations that are too complicated or expensive to
1555 perform by hand on floating-point numbers.  @w{ISO C99} defines
1556 functions to do these operations, which mostly involve changing single
1557 bits.
1558
1559 @comment math.h
1560 @comment ISO
1561 @deftypefun double copysign (double @var{x}, double @var{y})
1562 @comment math.h
1563 @comment ISO
1564 @deftypefunx float copysignf (float @var{x}, float @var{y})
1565 @comment math.h
1566 @comment ISO
1567 @deftypefunx {long double} copysignl (long double @var{x}, long double @var{y})
1568 These functions return @var{x} but with the sign of @var{y}.  They work
1569 even if @var{x} or @var{y} are NaN or zero.  Both of these can carry a
1570 sign (although not all implementations support it) and this is one of
1571 the few operations that can tell the difference.
1572
1573 @code{copysign} never raises an exception.
1574 @c except signalling NaNs
1575
1576 This function is defined in @w{IEC 559} (and the appendix with
1577 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
1578 @end deftypefun
1579
1580 @comment math.h
1581 @comment ISO
1582 @deftypefun int signbit (@emph{float-type} @var{x})
1583 @code{signbit} is a generic macro which can work on all floating-point
1584 types.  It returns a nonzero value if the value of @var{x} has its sign
1585 bit set.
1586
1587 This is not the same as @code{x < 0.0}, because @w{IEEE 754} floating
1588 point allows zero to be signed.  The comparison @code{-0.0 < 0.0} is
1589 false, but @code{signbit (-0.0)} will return a nonzero value.
1590 @end deftypefun
1591
1592 @comment math.h
1593 @comment ISO
1594 @deftypefun double nextafter (double @var{x}, double @var{y})
1595 @comment math.h
1596 @comment ISO
1597 @deftypefunx float nextafterf (float @var{x}, float @var{y})
1598 @comment math.h
1599 @comment ISO
1600 @deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y})
1601 The @code{nextafter} function returns the next representable neighbor of
1602 @var{x} in the direction towards @var{y}.  The size of the step between
1603 @var{x} and the result depends on the type of the result.  If
1604 @math{@var{x} = @var{y}} the function simply returns @var{y}.  If either
1605 value is @code{NaN}, @code{NaN} is returned.  Otherwise
1606 a value corresponding to the value of the least significant bit in the
1607 mantissa is added or subtracted, depending on the direction.
1608 @code{nextafter} will signal overflow or underflow if the result goes
1609 outside of the range of normalized numbers.
1610
1611 This function is defined in @w{IEC 559} (and the appendix with
1612 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
1613 @end deftypefun
1614
1615 @comment math.h
1616 @comment ISO
1617 @deftypefun double nexttoward (double @var{x}, long double @var{y})
1618 @comment math.h
1619 @comment ISO
1620 @deftypefunx float nexttowardf (float @var{x}, long double @var{y})
1621 @comment math.h
1622 @comment ISO
1623 @deftypefunx {long double} nexttowardl (long double @var{x}, long double @var{y})
1624 These functions are identical to the corresponding versions of
1625 @code{nextafter} except that their second argument is a @code{long
1626 double}.
1627 @end deftypefun
1628
1629 @cindex NaN
1630 @comment math.h
1631 @comment ISO
1632 @deftypefun double nan (const char *@var{tagp})
1633 @comment math.h
1634 @comment ISO
1635 @deftypefunx float nanf (const char *@var{tagp})
1636 @comment math.h
1637 @comment ISO
1638 @deftypefunx {long double} nanl (const char *@var{tagp})
1639 The @code{nan} function returns a representation of NaN, provided that
1640 NaN is supported by the target platform.
1641 @code{nan ("@var{n-char-sequence}")} is equivalent to
1642 @code{strtod ("NAN(@var{n-char-sequence})")}.
1643
1644 The argument @var{tagp} is used in an unspecified manner.  On @w{IEEE
1645 754} systems, there are many representations of NaN, and @var{tagp}
1646 selects one.  On other systems it may do nothing.
1647 @end deftypefun
1648
1649 @node FP Comparison Functions
1650 @subsection Floating-Point Comparison Functions
1651 @cindex unordered comparison
1652
1653 The standard C comparison operators provoke exceptions when one or other
1654 of the operands is NaN.  For example,
1655
1656 @smallexample
1657 int v = a < 1.0;
1658 @end smallexample
1659
1660 @noindent
1661 will raise an exception if @var{a} is NaN.  (This does @emph{not}
1662 happen with @code{==} and @code{!=}; those merely return false and true,
1663 respectively, when NaN is examined.)  Frequently this exception is
1664 undesirable.  @w{ISO C99} therefore defines comparison functions that
1665 do not raise exceptions when NaN is examined.  All of the functions are
1666 implemented as macros which allow their arguments to be of any
1667 floating-point type.  The macros are guaranteed to evaluate their
1668 arguments only once.
1669
1670 @comment math.h
1671 @comment ISO
1672 @deftypefn Macro int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1673 This macro determines whether the argument @var{x} is greater than
1674 @var{y}.  It is equivalent to @code{(@var{x}) > (@var{y})}, but no
1675 exception is raised if @var{x} or @var{y} are NaN.
1676 @end deftypefn
1677
1678 @comment math.h
1679 @comment ISO
1680 @deftypefn Macro int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1681 This macro determines whether the argument @var{x} is greater than or
1682 equal to @var{y}.  It is equivalent to @code{(@var{x}) >= (@var{y})}, but no
1683 exception is raised if @var{x} or @var{y} are NaN.
1684 @end deftypefn
1685
1686 @comment math.h
1687 @comment ISO
1688 @deftypefn Macro int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1689 This macro determines whether the argument @var{x} is less than @var{y}.
1690 It is equivalent to @code{(@var{x}) < (@var{y})}, but no exception is
1691 raised if @var{x} or @var{y} are NaN.
1692 @end deftypefn
1693
1694 @comment math.h
1695 @comment ISO
1696 @deftypefn Macro int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1697 This macro determines whether the argument @var{x} is less than or equal
1698 to @var{y}.  It is equivalent to @code{(@var{x}) <= (@var{y})}, but no
1699 exception is raised if @var{x} or @var{y} are NaN.
1700 @end deftypefn
1701
1702 @comment math.h
1703 @comment ISO
1704 @deftypefn Macro int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1705 This macro determines whether the argument @var{x} is less or greater
1706 than @var{y}.  It is equivalent to @code{(@var{x}) < (@var{y}) ||
1707 (@var{x}) > (@var{y})} (although it only evaluates @var{x} and @var{y}
1708 once), but no exception is raised if @var{x} or @var{y} are NaN.
1709
1710 This macro is not equivalent to @code{@var{x} != @var{y}}, because that
1711 expression is true if @var{x} or @var{y} are NaN.
1712 @end deftypefn
1713
1714 @comment math.h
1715 @comment ISO
1716 @deftypefn Macro int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1717 This macro determines whether its arguments are unordered.  In other
1718 words, it is true if @var{x} or @var{y} are NaN, and false otherwise.
1719 @end deftypefn
1720
1721 Not all machines provide hardware support for these operations.  On
1722 machines that don't, the macros can be very slow.  Therefore, you should
1723 not use these functions when NaN is not a concern.
1724
1725 @strong{Note:} There are no macros @code{isequal} or @code{isunequal}.
1726 They are unnecessary, because the @code{==} and @code{!=} operators do
1727 @emph{not} throw an exception if one or both of the operands are NaN.
1728
1729 @node Misc FP Arithmetic
1730 @subsection Miscellaneous FP arithmetic functions
1731 @cindex minimum
1732 @cindex maximum
1733 @cindex positive difference
1734 @cindex multiply-add
1735
1736 The functions in this section perform miscellaneous but common
1737 operations that are awkward to express with C operators.  On some
1738 processors these functions can use special machine instructions to
1739 perform these operations faster than the equivalent C code.
1740
1741 @comment math.h
1742 @comment ISO
1743 @deftypefun double fmin (double @var{x}, double @var{y})
1744 @comment math.h
1745 @comment ISO
1746 @deftypefunx float fminf (float @var{x}, float @var{y})
1747 @comment math.h
1748 @comment ISO
1749 @deftypefunx {long double} fminl (long double @var{x}, long double @var{y})
1750 The @code{fmin} function returns the lesser of the two values @var{x}
1751 and @var{y}.  It is similar to the expression
1752 @smallexample
1753 ((x) < (y) ? (x) : (y))
1754 @end smallexample
1755 except that @var{x} and @var{y} are only evaluated once.
1756
1757 If an argument is NaN, the other argument is returned.  If both arguments
1758 are NaN, NaN is returned.
1759 @end deftypefun
1760
1761 @comment math.h
1762 @comment ISO
1763 @deftypefun double fmax (double @var{x}, double @var{y})
1764 @comment math.h
1765 @comment ISO
1766 @deftypefunx float fmaxf (float @var{x}, float @var{y})
1767 @comment math.h
1768 @comment ISO
1769 @deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y})
1770 The @code{fmax} function returns the greater of the two values @var{x}
1771 and @var{y}.
1772
1773 If an argument is NaN, the other argument is returned.  If both arguments
1774 are NaN, NaN is returned.
1775 @end deftypefun
1776
1777 @comment math.h
1778 @comment ISO
1779 @deftypefun double fdim (double @var{x}, double @var{y})
1780 @comment math.h
1781 @comment ISO
1782 @deftypefunx float fdimf (float @var{x}, float @var{y})
1783 @comment math.h
1784 @comment ISO
1785 @deftypefunx {long double} fdiml (long double @var{x}, long double @var{y})
1786 The @code{fdim} function returns the positive difference between
1787 @var{x} and @var{y}.  The positive difference is @math{@var{x} -
1788 @var{y}} if @var{x} is greater than @var{y}, and @math{0} otherwise.
1789
1790 If @var{x}, @var{y}, or both are NaN, NaN is returned.
1791 @end deftypefun
1792
1793 @comment math.h
1794 @comment ISO
1795 @deftypefun double fma (double @var{x}, double @var{y}, double @var{z})
1796 @comment math.h
1797 @comment ISO
1798 @deftypefunx float fmaf (float @var{x}, float @var{y}, float @var{z})
1799 @comment math.h
1800 @comment ISO
1801 @deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z})
1802 @cindex butterfly
1803 The @code{fma} function performs floating-point multiply-add.  This is
1804 the operation @math{(@var{x} @mul{} @var{y}) + @var{z}}, but the
1805 intermediate result is not rounded to the destination type.  This can
1806 sometimes improve the precision of a calculation.
1807
1808 This function was introduced because some processors have a special
1809 instruction to perform multiply-add.  The C compiler cannot use it
1810 directly, because the expression @samp{x*y + z} is defined to round the
1811 intermediate result.  @code{fma} lets you choose when you want to round
1812 only once.
1813
1814 @vindex FP_FAST_FMA
1815 On processors which do not implement multiply-add in hardware,
1816 @code{fma} can be very slow since it must avoid intermediate rounding.
1817 @file{math.h} defines the symbols @code{FP_FAST_FMA},
1818 @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL} when the corresponding
1819 version of @code{fma} is no slower than the expression @samp{x*y + z}.
1820 In the GNU C library, this always means the operation is implemented in
1821 hardware.
1822 @end deftypefun
1823
1824 @node Complex Numbers
1825 @section Complex Numbers
1826 @pindex complex.h
1827 @cindex complex numbers
1828
1829 @w{ISO C99} introduces support for complex numbers in C.  This is done
1830 with a new type qualifier, @code{complex}.  It is a keyword if and only
1831 if @file{complex.h} has been included.  There are three complex types,
1832 corresponding to the three real types:  @code{float complex},
1833 @code{double complex}, and @code{long double complex}.
1834
1835 To construct complex numbers you need a way to indicate the imaginary
1836 part of a number.  There is no standard notation for an imaginary
1837 floating point constant.  Instead, @file{complex.h} defines two macros
1838 that can be used to create complex numbers.
1839
1840 @deftypevr Macro {const float complex} _Complex_I
1841 This macro is a representation of the complex number ``@math{0+1i}''.
1842 Multiplying a real floating-point value by @code{_Complex_I} gives a
1843 complex number whose value is purely imaginary.  You can use this to
1844 construct complex constants:
1845
1846 @smallexample
1847 @math{3.0 + 4.0i} = @code{3.0 + 4.0 * _Complex_I}
1848 @end smallexample
1849
1850 Note that @code{_Complex_I * _Complex_I} has the value @code{-1}, but
1851 the type of that value is @code{complex}.
1852 @end deftypevr
1853
1854 @c Put this back in when gcc supports _Imaginary_I.  It's too confusing.
1855 @ignore
1856 @noindent
1857 Without an optimizing compiler this is more expensive than the use of
1858 @code{_Imaginary_I} but with is better than nothing.  You can avoid all
1859 the hassles if you use the @code{I} macro below if the name is not
1860 problem.
1861
1862 @deftypevr Macro {const float imaginary} _Imaginary_I
1863 This macro is a representation of the value ``@math{1i}''.  I.e., it is
1864 the value for which
1865
1866 @smallexample
1867 _Imaginary_I * _Imaginary_I = -1
1868 @end smallexample
1869
1870 @noindent
1871 The result is not of type @code{float imaginary} but instead @code{float}.
1872 One can use it to easily construct complex number like in
1873
1874 @smallexample
1875 3.0 - _Imaginary_I * 4.0
1876 @end smallexample
1877
1878 @noindent
1879 which results in the complex number with a real part of 3.0 and a
1880 imaginary part -4.0.
1881 @end deftypevr
1882 @end ignore
1883
1884 @noindent
1885 @code{_Complex_I} is a bit of a mouthful.  @file{complex.h} also defines
1886 a shorter name for the same constant.
1887
1888 @deftypevr Macro {const float complex} I
1889 This macro has exactly the same value as @code{_Complex_I}.  Most of the
1890 time it is preferable.  However, it causes problems if you want to use
1891 the identifier @code{I} for something else.  You can safely write
1892
1893 @smallexample
1894 #include <complex.h>
1895 #undef I
1896 @end smallexample
1897
1898 @noindent
1899 if you need @code{I} for your own purposes.  (In that case we recommend
1900 you also define some other short name for @code{_Complex_I}, such as
1901 @code{J}.)
1902
1903 @ignore
1904 If the implementation does not support the @code{imaginary} types
1905 @code{I} is defined as @code{_Complex_I} which is the second best
1906 solution.  It still can be used in the same way but requires a most
1907 clever compiler to get the same results.
1908 @end ignore
1909 @end deftypevr
1910
1911 @node Operations on Complex
1912 @section Projections, Conjugates, and Decomposing of Complex Numbers
1913 @cindex project complex numbers
1914 @cindex conjugate complex numbers
1915 @cindex decompose complex numbers
1916 @pindex complex.h
1917
1918 @w{ISO C99} also defines functions that perform basic operations on
1919 complex numbers, such as decomposition and conjugation.  The prototypes
1920 for all these functions are in @file{complex.h}.  All functions are
1921 available in three variants, one for each of the three complex types.
1922
1923 @comment complex.h
1924 @comment ISO
1925 @deftypefun double creal (complex double @var{z})
1926 @comment complex.h
1927 @comment ISO
1928 @deftypefunx float crealf (complex float @var{z})
1929 @comment complex.h
1930 @comment ISO
1931 @deftypefunx {long double} creall (complex long double @var{z})
1932 These functions return the real part of the complex number @var{z}.
1933 @end deftypefun
1934
1935 @comment complex.h
1936 @comment ISO
1937 @deftypefun double cimag (complex double @var{z})
1938 @comment complex.h
1939 @comment ISO
1940 @deftypefunx float cimagf (complex float @var{z})
1941 @comment complex.h
1942 @comment ISO
1943 @deftypefunx {long double} cimagl (complex long double @var{z})
1944 These functions return the imaginary part of the complex number @var{z}.
1945 @end deftypefun
1946
1947 @comment complex.h
1948 @comment ISO
1949 @deftypefun {complex double} conj (complex double @var{z})
1950 @comment complex.h
1951 @comment ISO
1952 @deftypefunx {complex float} conjf (complex float @var{z})
1953 @comment complex.h
1954 @comment ISO
1955 @deftypefunx {complex long double} conjl (complex long double @var{z})
1956 These functions return the conjugate value of the complex number
1957 @var{z}.  The conjugate of a complex number has the same real part and a
1958 negated imaginary part.  In other words, @samp{conj(a + bi) = a + -bi}.
1959 @end deftypefun
1960
1961 @comment complex.h
1962 @comment ISO
1963 @deftypefun double carg (complex double @var{z})
1964 @comment complex.h
1965 @comment ISO
1966 @deftypefunx float cargf (complex float @var{z})
1967 @comment complex.h
1968 @comment ISO
1969 @deftypefunx {long double} cargl (complex long double @var{z})
1970 These functions return the argument of the complex number @var{z}.
1971 The argument of a complex number is the angle in the complex plane
1972 between the positive real axis and a line passing through zero and the
1973 number.  This angle is measured in the usual fashion and ranges from @math{0}
1974 to @math{2@pi{}}.
1975
1976 @code{carg} has a branch cut along the positive real axis.
1977 @end deftypefun
1978
1979 @comment complex.h
1980 @comment ISO
1981 @deftypefun {complex double} cproj (complex double @var{z})
1982 @comment complex.h
1983 @comment ISO
1984 @deftypefunx {complex float} cprojf (complex float @var{z})
1985 @comment complex.h
1986 @comment ISO
1987 @deftypefunx {complex long double} cprojl (complex long double @var{z})
1988 These functions return the projection of the complex value @var{z} onto
1989 the Riemann sphere.  Values with a infinite imaginary part are projected
1990 to positive infinity on the real axis, even if the real part is NaN.  If
1991 the real part is infinite, the result is equivalent to
1992
1993 @smallexample
1994 INFINITY + I * copysign (0.0, cimag (z))
1995 @end smallexample
1996 @end deftypefun
1997
1998 @node Parsing of Numbers
1999 @section Parsing of Numbers
2000 @cindex parsing numbers (in formatted input)
2001 @cindex converting strings to numbers
2002 @cindex number syntax, parsing
2003 @cindex syntax, for reading numbers
2004
2005 This section describes functions for ``reading'' integer and
2006 floating-point numbers from a string.  It may be more convenient in some
2007 cases to use @code{sscanf} or one of the related functions; see
2008 @ref{Formatted Input}.  But often you can make a program more robust by
2009 finding the tokens in the string by hand, then converting the numbers
2010 one by one.
2011
2012 @menu
2013 * Parsing of Integers::         Functions for conversion of integer values.
2014 * Parsing of Floats::           Functions for conversion of floating-point
2015                                  values.
2016 @end menu
2017
2018 @node Parsing of Integers
2019 @subsection Parsing of Integers
2020
2021 @pindex stdlib.h
2022 @pindex wchar.h
2023 The @samp{str} functions are declared in @file{stdlib.h} and those
2024 beginning with @samp{wcs} are declared in @file{wchar.h}.  One might
2025 wonder about the use of @code{restrict} in the prototypes of the
2026 functions in this section.  It is seemingly useless but the @w{ISO C}
2027 standard uses it (for the functions defined there) so we have to do it
2028 as well.
2029
2030 @comment stdlib.h
2031 @comment ISO
2032 @deftypefun {long int} strtol (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2033 The @code{strtol} (``string-to-long'') function converts the initial
2034 part of @var{string} to a signed integer, which is returned as a value
2035 of type @code{long int}.
2036
2037 This function attempts to decompose @var{string} as follows:
2038
2039 @itemize @bullet
2040 @item
2041 A (possibly empty) sequence of whitespace characters.  Which characters
2042 are whitespace is determined by the @code{isspace} function
2043 (@pxref{Classification of Characters}).  These are discarded.
2044
2045 @item
2046 An optional plus or minus sign (@samp{+} or @samp{-}).
2047
2048 @item
2049 A nonempty sequence of digits in the radix specified by @var{base}.
2050
2051 If @var{base} is zero, decimal radix is assumed unless the series of
2052 digits begins with @samp{0} (specifying octal radix), or @samp{0x} or
2053 @samp{0X} (specifying hexadecimal radix); in other words, the same
2054 syntax used for integer constants in C.
2055
2056 Otherwise @var{base} must have a value between @code{2} and @code{36}.
2057 If @var{base} is @code{16}, the digits may optionally be preceded by
2058 @samp{0x} or @samp{0X}.  If base has no legal value the value returned
2059 is @code{0l} and the global variable @code{errno} is set to @code{EINVAL}.
2060
2061 @item
2062 Any remaining characters in the string.  If @var{tailptr} is not a null
2063 pointer, @code{strtol} stores a pointer to this tail in
2064 @code{*@var{tailptr}}.
2065 @end itemize
2066
2067 If the string is empty, contains only whitespace, or does not contain an
2068 initial substring that has the expected syntax for an integer in the
2069 specified @var{base}, no conversion is performed.  In this case,
2070 @code{strtol} returns a value of zero and the value stored in
2071 @code{*@var{tailptr}} is the value of @var{string}.
2072
2073 In a locale other than the standard @code{"C"} locale, this function
2074 may recognize additional implementation-dependent syntax.
2075
2076 If the string has valid syntax for an integer but the value is not
2077 representable because of overflow, @code{strtol} returns either
2078 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as
2079 appropriate for the sign of the value.  It also sets @code{errno}
2080 to @code{ERANGE} to indicate there was overflow.
2081
2082 You should not check for errors by examining the return value of
2083 @code{strtol}, because the string might be a valid representation of
2084 @code{0l}, @code{LONG_MAX}, or @code{LONG_MIN}.  Instead, check whether
2085 @var{tailptr} points to what you expect after the number
2086 (e.g. @code{'\0'} if the string should end after the number).  You also
2087 need to clear @var{errno} before the call and check it afterward, in
2088 case there was overflow.
2089
2090 There is an example at the end of this section.
2091 @end deftypefun
2092
2093 @comment wchar.h
2094 @comment ISO
2095 @deftypefun {long int} wcstol (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2096 The @code{wcstol} function is equivalent to the @code{strtol} function
2097 in nearly all aspects but handles wide character strings.
2098
2099 The @code{wcstol} function was introduced in @w{Amendment 1} of @w{ISO C90}.
2100 @end deftypefun
2101
2102 @comment stdlib.h
2103 @comment ISO
2104 @deftypefun {unsigned long int} strtoul (const char *retrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2105 The @code{strtoul} (``string-to-unsigned-long'') function is like
2106 @code{strtol} except it converts to an @code{unsigned long int} value.
2107 The syntax is the same as described above for @code{strtol}.  The value
2108 returned on overflow is @code{ULONG_MAX} (@pxref{Range of Type}).
2109
2110 If @var{string} depicts a negative number, @code{strtoul} acts the same
2111 as @var{strtol} but casts the result to an unsigned integer.  That means
2112 for example that @code{strtoul} on @code{"-1"} returns @code{ULONG_MAX}
2113 and an input more negative than @code{LONG_MIN} returns
2114 (@code{ULONG_MAX} + 1) / 2.
2115
2116 @code{strtoul} sets @var{errno} to @code{EINVAL} if @var{base} is out of
2117 range, or @code{ERANGE} on overflow.
2118 @end deftypefun
2119
2120 @comment wchar.h
2121 @comment ISO
2122 @deftypefun {unsigned long int} wcstoul (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2123 The @code{wcstoul} function is equivalent to the @code{strtoul} function
2124 in nearly all aspects but handles wide character strings.
2125
2126 The @code{wcstoul} function was introduced in @w{Amendment 1} of @w{ISO C90}.
2127 @end deftypefun
2128
2129 @comment stdlib.h
2130 @comment ISO
2131 @deftypefun {long long int} strtoll (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2132 The @code{strtoll} function is like @code{strtol} except that it returns
2133 a @code{long long int} value, and accepts numbers with a correspondingly
2134 larger range.
2135
2136 If the string has valid syntax for an integer but the value is not
2137 representable because of overflow, @code{strtoll} returns either
2138 @code{LONG_LONG_MAX} or @code{LONG_LONG_MIN} (@pxref{Range of Type}), as
2139 appropriate for the sign of the value.  It also sets @code{errno} to
2140 @code{ERANGE} to indicate there was overflow.
2141
2142 The @code{strtoll} function was introduced in @w{ISO C99}.
2143 @end deftypefun
2144
2145 @comment wchar.h
2146 @comment ISO
2147 @deftypefun {long long int} wcstoll (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2148 The @code{wcstoll} function is equivalent to the @code{strtoll} function
2149 in nearly all aspects but handles wide character strings.
2150
2151 The @code{wcstoll} function was introduced in @w{Amendment 1} of @w{ISO C90}.
2152 @end deftypefun
2153
2154 @comment stdlib.h
2155 @comment BSD
2156 @deftypefun {long long int} strtoq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2157 @code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}.
2158 @end deftypefun
2159
2160 @comment wchar.h
2161 @comment GNU
2162 @deftypefun {long long int} wcstoq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2163 The @code{wcstoq} function is equivalent to the @code{strtoq} function
2164 in nearly all aspects but handles wide character strings.
2165
2166 The @code{wcstoq} function is a GNU extension.
2167 @end deftypefun
2168
2169 @comment stdlib.h
2170 @comment ISO
2171 @deftypefun {unsigned long long int} strtoull (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2172 The @code{strtoull} function is related to @code{strtoll} the same way
2173 @code{strtoul} is related to @code{strtol}.
2174
2175 The @code{strtoull} function was introduced in @w{ISO C99}.
2176 @end deftypefun
2177
2178 @comment wchar.h
2179 @comment ISO
2180 @deftypefun {unsigned long long int} wcstoull (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2181 The @code{wcstoull} function is equivalent to the @code{strtoull} function
2182 in nearly all aspects but handles wide character strings.
2183
2184 The @code{wcstoull} function was introduced in @w{Amendment 1} of @w{ISO C90}.
2185 @end deftypefun
2186
2187 @comment stdlib.h
2188 @comment BSD
2189 @deftypefun {unsigned long long int} strtouq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2190 @code{strtouq} is the BSD name for @code{strtoull}.
2191 @end deftypefun
2192
2193 @comment wchar.h
2194 @comment GNU
2195 @deftypefun {unsigned long long int} wcstouq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2196 The @code{wcstouq} function is equivalent to the @code{strtouq} function
2197 in nearly all aspects but handles wide character strings.
2198
2199 The @code{wcstouq} function is a GNU extension.
2200 @end deftypefun
2201
2202 @comment inttypes.h
2203 @comment ISO
2204 @deftypefun intmax_t strtoimax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2205 The @code{strtoimax} function is like @code{strtol} except that it returns
2206 a @code{intmax_t} value, and accepts numbers of a corresponding range.
2207
2208 If the string has valid syntax for an integer but the value is not
2209 representable because of overflow, @code{strtoimax} returns either
2210 @code{INTMAX_MAX} or @code{INTMAX_MIN} (@pxref{Integers}), as
2211 appropriate for the sign of the value.  It also sets @code{errno} to
2212 @code{ERANGE} to indicate there was overflow.
2213
2214 See @ref{Integers} for a description of the @code{intmax_t} type.  The
2215 @code{strtoimax} function was introduced in @w{ISO C99}.
2216 @end deftypefun
2217
2218 @comment wchar.h
2219 @comment ISO
2220 @deftypefun intmax_t wcstoimax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2221 The @code{wcstoimax} function is equivalent to the @code{strtoimax} function
2222 in nearly all aspects but handles wide character strings.
2223
2224 The @code{wcstoimax} function was introduced in @w{ISO C99}.
2225 @end deftypefun
2226
2227 @comment inttypes.h
2228 @comment ISO
2229 @deftypefun uintmax_t strtoumax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2230 The @code{strtoumax} function is related to @code{strtoimax}
2231 the same way that @code{strtoul} is related to @code{strtol}.
2232
2233 See @ref{Integers} for a description of the @code{intmax_t} type.  The
2234 @code{strtoumax} function was introduced in @w{ISO C99}.
2235 @end deftypefun
2236
2237 @comment wchar.h
2238 @comment ISO
2239 @deftypefun uintmax_t wcstoumax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2240 The @code{wcstoumax} function is equivalent to the @code{strtoumax} function
2241 in nearly all aspects but handles wide character strings.
2242
2243 The @code{wcstoumax} function was introduced in @w{ISO C99}.
2244 @end deftypefun
2245
2246 @comment stdlib.h
2247 @comment ISO
2248 @deftypefun {long int} atol (const char *@var{string})
2249 This function is similar to the @code{strtol} function with a @var{base}
2250 argument of @code{10}, except that it need not detect overflow errors.
2251 The @code{atol} function is provided mostly for compatibility with
2252 existing code; using @code{strtol} is more robust.
2253 @end deftypefun
2254
2255 @comment stdlib.h
2256 @comment ISO
2257 @deftypefun int atoi (const char *@var{string})
2258 This function is like @code{atol}, except that it returns an @code{int}.
2259 The @code{atoi} function is also considered obsolete; use @code{strtol}
2260 instead.
2261 @end deftypefun
2262
2263 @comment stdlib.h
2264 @comment ISO
2265 @deftypefun {long long int} atoll (const char *@var{string})
2266 This function is similar to @code{atol}, except it returns a @code{long
2267 long int}.
2268
2269 The @code{atoll} function was introduced in @w{ISO C99}.  It too is
2270 obsolete (despite having just been added); use @code{strtoll} instead.
2271 @end deftypefun
2272
2273 All the functions mentioned in this section so far do not handle
2274 alternative representations of characters as described in the locale
2275 data.  Some locales specify thousands separator and the way they have to
2276 be used which can help to make large numbers more readable.  To read
2277 such numbers one has to use the @code{scanf} functions with the @samp{'}
2278 flag.
2279
2280 Here is a function which parses a string as a sequence of integers and
2281 returns the sum of them:
2282
2283 @smallexample
2284 int
2285 sum_ints_from_string (char *string)
2286 @{
2287   int sum = 0;
2288
2289   while (1) @{
2290     char *tail;
2291     int next;
2292
2293     /* @r{Skip whitespace by hand, to detect the end.}  */
2294     while (isspace (*string)) string++;
2295     if (*string == 0)
2296       break;
2297
2298     /* @r{There is more nonwhitespace,}  */
2299     /* @r{so it ought to be another number.}  */
2300     errno = 0;
2301     /* @r{Parse it.}  */
2302     next = strtol (string, &tail, 0);
2303     /* @r{Add it in, if not overflow.}  */
2304     if (errno)
2305       printf ("Overflow\n");
2306     else
2307       sum += next;
2308     /* @r{Advance past it.}  */
2309     string = tail;
2310   @}
2311
2312   return sum;
2313 @}
2314 @end smallexample
2315
2316 @node Parsing of Floats
2317 @subsection Parsing of Floats
2318
2319 @pindex stdlib.h
2320 The @samp{str} functions are declared in @file{stdlib.h} and those
2321 beginning with @samp{wcs} are declared in @file{wchar.h}.  One might
2322 wonder about the use of @code{restrict} in the prototypes of the
2323 functions in this section.  It is seemingly useless but the @w{ISO C}
2324 standard uses it (for the functions defined there) so we have to do it
2325 as well.
2326
2327 @comment stdlib.h
2328 @comment ISO
2329 @deftypefun double strtod (const char *restrict @var{string}, char **restrict @var{tailptr})
2330 The @code{strtod} (``string-to-double'') function converts the initial
2331 part of @var{string} to a floating-point number, which is returned as a
2332 value of type @code{double}.
2333
2334 This function attempts to decompose @var{string} as follows:
2335
2336 @itemize @bullet
2337 @item
2338 A (possibly empty) sequence of whitespace characters.  Which characters
2339 are whitespace is determined by the @code{isspace} function
2340 (@pxref{Classification of Characters}).  These are discarded.
2341
2342 @item
2343 An optional plus or minus sign (@samp{+} or @samp{-}).
2344
2345 @item A floating point number in decimal or hexadecimal format.  The
2346 decimal format is:
2347 @itemize @minus
2348
2349 @item
2350 A nonempty sequence of digits optionally containing a decimal-point
2351 character---normally @samp{.}, but it depends on the locale
2352 (@pxref{General Numeric}).
2353
2354 @item
2355 An optional exponent part, consisting of a character @samp{e} or
2356 @samp{E}, an optional sign, and a sequence of digits.
2357
2358 @end itemize
2359
2360 The hexadecimal format is as follows:
2361 @itemize @minus
2362
2363 @item
2364 A 0x or 0X followed by a nonempty sequence of hexadecimal digits
2365 optionally containing a decimal-point character---normally @samp{.}, but
2366 it depends on the locale (@pxref{General Numeric}).
2367
2368 @item
2369 An optional binary-exponent part, consisting of a character @samp{p} or
2370 @samp{P}, an optional sign, and a sequence of digits.
2371
2372 @end itemize
2373
2374 @item
2375 Any remaining characters in the string.  If @var{tailptr} is not a null
2376 pointer, a pointer to this tail of the string is stored in
2377 @code{*@var{tailptr}}.
2378 @end itemize
2379
2380 If the string is empty, contains only whitespace, or does not contain an
2381 initial substring that has the expected syntax for a floating-point
2382 number, no conversion is performed.  In this case, @code{strtod} returns
2383 a value of zero and the value returned in @code{*@var{tailptr}} is the
2384 value of @var{string}.
2385
2386 In a locale other than the standard @code{"C"} or @code{"POSIX"} locales,
2387 this function may recognize additional locale-dependent syntax.
2388
2389 If the string has valid syntax for a floating-point number but the value
2390 is outside the range of a @code{double}, @code{strtod} will signal
2391 overflow or underflow as described in @ref{Math Error Reporting}.
2392
2393 @code{strtod} recognizes four special input strings.  The strings
2394 @code{"inf"} and @code{"infinity"} are converted to @math{@infinity{}},
2395 or to the largest representable value if the floating-point format
2396 doesn't support infinities.  You can prepend a @code{"+"} or @code{"-"}
2397 to specify the sign.  Case is ignored when scanning these strings.
2398
2399 The strings @code{"nan"} and @code{"nan(@var{chars@dots{}})"} are converted
2400 to NaN.  Again, case is ignored.  If @var{chars@dots{}} are provided, they
2401 are used in some unspecified fashion to select a particular
2402 representation of NaN (there can be several).
2403
2404 Since zero is a valid result as well as the value returned on error, you
2405 should check for errors in the same way as for @code{strtol}, by
2406 examining @var{errno} and @var{tailptr}.
2407 @end deftypefun
2408
2409 @comment stdlib.h
2410 @comment ISO
2411 @deftypefun float strtof (const char *@var{string}, char **@var{tailptr})
2412 @comment stdlib.h
2413 @comment ISO
2414 @deftypefunx {long double} strtold (const char *@var{string}, char **@var{tailptr})
2415 These functions are analogous to @code{strtod}, but return @code{float}
2416 and @code{long double} values respectively.  They report errors in the
2417 same way as @code{strtod}.  @code{strtof} can be substantially faster
2418 than @code{strtod}, but has less precision; conversely, @code{strtold}
2419 can be much slower but has more precision (on systems where @code{long
2420 double} is a separate type).
2421
2422 These functions have been GNU extensions and are new to @w{ISO C99}.
2423 @end deftypefun
2424
2425 @comment wchar.h
2426 @comment ISO
2427 @deftypefun double wcstod (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr})
2428 @comment stdlib.h
2429 @comment ISO
2430 @deftypefunx float wcstof (const wchar_t *@var{string}, wchar_t **@var{tailptr})
2431 @comment stdlib.h
2432 @comment ISO
2433 @deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr})
2434 The @code{wcstod}, @code{wcstof}, and @code{wcstol} functions are
2435 equivalent in nearly all aspect to the @code{strtod}, @code{strtof}, and
2436 @code{strtold} functions but it handles wide character string.
2437
2438 The @code{wcstod} function was introduced in @w{Amendment 1} of @w{ISO
2439 C90}.  The @code{wcstof} and @code{wcstold} functions were introduced in
2440 @w{ISO C99}.
2441 @end deftypefun
2442
2443 @comment stdlib.h
2444 @comment ISO
2445 @deftypefun double atof (const char *@var{string})
2446 This function is similar to the @code{strtod} function, except that it
2447 need not detect overflow and underflow errors.  The @code{atof} function
2448 is provided mostly for compatibility with existing code; using
2449 @code{strtod} is more robust.
2450 @end deftypefun
2451
2452 The GNU C library also provides @samp{_l} versions of these functions,
2453 which take an additional argument, the locale to use in conversion.
2454 @xref{Parsing of Integers}.
2455
2456 @node System V Number Conversion
2457 @section Old-fashioned System V number-to-string functions
2458
2459 The old @w{System V} C library provided three functions to convert
2460 numbers to strings, with unusual and hard-to-use semantics.  The GNU C
2461 library also provides these functions and some natural extensions.
2462
2463 These functions are only available in glibc and on systems descended
2464 from AT&T Unix.  Therefore, unless these functions do precisely what you
2465 need, it is better to use @code{sprintf}, which is standard.
2466
2467 All these functions are defined in @file{stdlib.h}.
2468
2469 @comment stdlib.h
2470 @comment SVID, Unix98
2471 @deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2472 The function @code{ecvt} converts the floating-point number @var{value}
2473 to a string with at most @var{ndigit} decimal digits.  The
2474 returned string contains no decimal point or sign. The first digit of
2475 the string is non-zero (unless @var{value} is actually zero) and the
2476 last digit is rounded to nearest.  @code{*@var{decpt}} is set to the
2477 index in the string of the first digit after the decimal point.
2478 @code{*@var{neg}} is set to a nonzero value if @var{value} is negative,
2479 zero otherwise.
2480
2481 If @var{ndigit} decimal digits would exceed the precision of a
2482 @code{double} it is reduced to a system-specific value.
2483
2484 The returned string is statically allocated and overwritten by each call
2485 to @code{ecvt}.
2486
2487 If @var{value} is zero, it is implementation defined whether
2488 @code{*@var{decpt}} is @code{0} or @code{1}.
2489
2490 For example: @code{ecvt (12.3, 5, &d, &n)} returns @code{"12300"}
2491 and sets @var{d} to @code{2} and @var{n} to @code{0}.
2492 @end deftypefun
2493
2494 @comment stdlib.h
2495 @comment SVID, Unix98
2496 @deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2497 The function @code{fcvt} is like @code{ecvt}, but @var{ndigit} specifies
2498 the number of digits after the decimal point.  If @var{ndigit} is less
2499 than zero, @var{value} is rounded to the @math{@var{ndigit}+1}'th place to the
2500 left of the decimal point.  For example, if @var{ndigit} is @code{-1},
2501 @var{value} will be rounded to the nearest 10.  If @var{ndigit} is
2502 negative and larger than the number of digits to the left of the decimal
2503 point in @var{value}, @var{value} will be rounded to one significant digit.
2504
2505 If @var{ndigit} decimal digits would exceed the precision of a
2506 @code{double} it is reduced to a system-specific value.
2507
2508 The returned string is statically allocated and overwritten by each call
2509 to @code{fcvt}.
2510 @end deftypefun
2511
2512 @comment stdlib.h
2513 @comment SVID, Unix98
2514 @deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf})
2515 @code{gcvt} is functionally equivalent to @samp{sprintf(buf, "%*g",
2516 ndigit, value}.  It is provided only for compatibility's sake.  It
2517 returns @var{buf}.
2518
2519 If @var{ndigit} decimal digits would exceed the precision of a
2520 @code{double} it is reduced to a system-specific value.
2521 @end deftypefun
2522
2523 As extensions, the GNU C library provides versions of these three
2524 functions that take @code{long double} arguments.
2525
2526 @comment stdlib.h
2527 @comment GNU
2528 @deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2529 This function is equivalent to @code{ecvt} except that it takes a
2530 @code{long double} for the first parameter and that @var{ndigit} is
2531 restricted by the precision of a @code{long double}.
2532 @end deftypefun
2533
2534 @comment stdlib.h
2535 @comment GNU
2536 @deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2537 This function is equivalent to @code{fcvt} except that it
2538 takes a @code{long double} for the first parameter and that @var{ndigit} is
2539 restricted by the precision of a @code{long double}.
2540 @end deftypefun
2541
2542 @comment stdlib.h
2543 @comment GNU
2544 @deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf})
2545 This function is equivalent to @code{gcvt} except that it takes a
2546 @code{long double} for the first parameter and that @var{ndigit} is
2547 restricted by the precision of a @code{long double}.
2548 @end deftypefun
2549
2550
2551 @cindex gcvt_r
2552 The @code{ecvt} and @code{fcvt} functions, and their @code{long double}
2553 equivalents, all return a string located in a static buffer which is
2554 overwritten by the next call to the function.  The GNU C library
2555 provides another set of extended functions which write the converted
2556 string into a user-supplied buffer.  These have the conventional
2557 @code{_r} suffix.
2558
2559 @code{gcvt_r} is not necessary, because @code{gcvt} already uses a
2560 user-supplied buffer.
2561
2562 @comment stdlib.h
2563 @comment GNU
2564 @deftypefun int ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2565 The @code{ecvt_r} function is the same as @code{ecvt}, except
2566 that it places its result into the user-specified buffer pointed to by
2567 @var{buf}, with length @var{len}.  The return value is @code{-1} in
2568 case of an error and zero otherwise.
2569
2570 This function is a GNU extension.
2571 @end deftypefun
2572
2573 @comment stdlib.h
2574 @comment SVID, Unix98
2575 @deftypefun int fcvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2576 The @code{fcvt_r} function is the same as @code{fcvt}, except that it
2577 places its result into the user-specified buffer pointed to by
2578 @var{buf}, with length @var{len}.  The return value is @code{-1} in
2579 case of an error and zero otherwise.
2580
2581 This function is a GNU extension.
2582 @end deftypefun
2583
2584 @comment stdlib.h
2585 @comment GNU
2586 @deftypefun int qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2587 The @code{qecvt_r} function is the same as @code{qecvt}, except
2588 that it places its result into the user-specified buffer pointed to by
2589 @var{buf}, with length @var{len}.  The return value is @code{-1} in
2590 case of an error and zero otherwise.
2591
2592 This function is a GNU extension.
2593 @end deftypefun
2594
2595 @comment stdlib.h
2596 @comment GNU
2597 @deftypefun int qfcvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2598 The @code{qfcvt_r} function is the same as @code{qfcvt}, except
2599 that it places its result into the user-specified buffer pointed to by
2600 @var{buf}, with length @var{len}.  The return value is @code{-1} in
2601 case of an error and zero otherwise.
2602
2603 This function is a GNU extension.
2604 @end deftypefun