1 @c We need some definitions here.
23 @node Arithmetic, Date and Time, Mathematics, Top
24 @chapter Low-Level Arithmetic Functions
26 This chapter contains information about functions for doing basic
27 arithmetic operations, such as splitting a float into its integer and
28 fractional parts or retrieving the imaginary part of a complex value.
29 These functions are declared in the header files @file{math.h} and
33 * Infinity:: What is Infinity and how to test for it.
34 * Not a Number:: Making NaNs and testing for NaNs.
35 * Imaginary Unit:: Constructing complex Numbers.
36 * Predicates on Floats:: Testing for infinity and for NaNs.
37 * Floating-Point Classes:: Classify floating-point numbers.
38 * Operations on Complex:: Projections, Conjugates, and Decomposing.
39 * Absolute Value:: Absolute value functions.
40 * Normalization Functions:: Hacks for radix-2 representations.
41 * Rounding and Remainders:: Determining the integer and
42 fractional parts of a float.
43 * Arithmetic on FP Values:: Setting and Modifying Single Bits of FP Values.
44 * Special arithmetic on FPs:: Special Arithmetic on FPs.
45 * Integer Division:: Functions for performing integer
47 * Parsing of Numbers:: Functions for ``reading'' numbers
49 * Old-style number conversion:: Low-level number to string conversion.
53 @section Infinity Values
55 @cindex IEEE floating point
57 Mathematical operations easily can produce as the result values which
58 are not representable by the floating-point format. The functions in
59 the mathematics library also have this problem. The situation is
60 generally solved by raising an overflow exception and by returning a
63 The @w{IEEE 754} floating-point defines a special value to be used in
64 these situations. There is a special value for infinity.
68 @deftypevr Macro float INFINITY
69 An expression representing the infinite value. @code{INFINITY} values are
70 produced by mathematical operations like @code{1.0 / 0.0}. It is
71 possible to continue the computations with this value since the basic
72 operations as well as the mathematical library functions are prepared to
73 handle values like this.
75 Beside @code{INFINITY} also the value @code{-INFINITY} is representable
76 and it is handled differently if needed. It is possible to test a
77 value for infiniteness using a simple comparison but the
78 recommended way is to use the the @code{isinf} function.
80 This macro was introduced in the @w{ISO C 9X} standard.
84 The macros @code{HUGE_VAL}, @code{HUGE_VALF} and @code{HUGE_VALL} are
85 defined in a similar way but they are not required to represent the
86 infinite value, only a very large value (@pxref{Domain and Range Errors}).
87 If actually infinity is wanted, @code{INFINITY} should be used.
91 @section ``Not a Number'' Values
94 @cindex IEEE floating point
96 The IEEE floating point format used by most modern computers supports
97 values that are ``not a number''. These values are called @dfn{NaNs}.
98 ``Not a number'' values result from certain operations which have no
99 meaningful numeric result, such as zero divided by zero or infinity
102 One noteworthy property of NaNs is that they are not equal to
103 themselves. Thus, @code{x == x} can be 0 if the value of @code{x} is a
104 NaN. You can use this to test whether a value is a NaN or not: if it is
105 not equal to itself, then it is a NaN. But the recommended way to test
106 for a NaN is with the @code{isnan} function (@pxref{Predicates on Floats}).
108 Almost any arithmetic operation in which one argument is a NaN returns
113 @deftypevr Macro float NAN
114 An expression representing a value which is ``not a number''. This
115 macro is a GNU extension, available only on machines that support ``not
116 a number'' values---that is to say, on all machines that support IEEE
119 You can use @samp{#ifdef NAN} to test whether the machine supports
120 NaNs. (Of course, you must arrange for GNU extensions to be visible,
121 such as by defining @code{_GNU_SOURCE}, and then you must include
126 @section Constructing complex Numbers
129 To construct complex numbers it is necessary have a way to express the
130 imaginary part of the numbers. In mathematics one uses the symbol ``i''
131 to mark a number as imaginary. For convenience the @file{complex.h}
132 header defines two macros which allow to use a similar easy notation.
134 @deftypevr Macro {const float complex} _Complex_I
135 This macro is a representation of the complex number ``@math{0+1i}''.
139 _Complex_I * _Complex_I = -1
143 leads to a real-valued result. If no @code{imaginary} types are
144 available it is easiest to use this value to construct complex numbers
148 3.0 - _Complex_I * 4.0
153 Without an optimizing compiler this is more expensive than the use of
154 @code{_Imaginary_I} but with is better than nothing. You can avoid all
155 the hassles if you use the @code{I} macro below if the name is not
158 @deftypevr Macro {const float imaginary} _Imaginary_I
159 This macro is a representation of the value ``@math{1i}''. I.e., it is
163 _Imaginary_I * _Imaginary_I = -1
167 The result is not of type @code{float imaginary} but instead @code{float}.
168 One can use it to easily construct complex number like in
171 3.0 - _Imaginary_I * 4.0
175 which results in the complex number with a real part of 3.0 and a
180 A more intuitive approach is to use the following macro.
182 @deftypevr Macro {const float imaginary} I
183 This macro has exactly the same value as @code{_Imaginary_I}. The
184 problem is that the name @code{I} very easily can clash with macros or
185 variables in programs and so it might be a good idea to avoid this name
186 and stay at the safe side by using @code{_Imaginary_I}.
188 If the implementation does not support the @code{imaginary} types
189 @code{I} is defined as @code{_Complex_I} which is the second best
190 solution. It still can be used in the same way but requires a most
191 clever compiler to get the same results.
195 @node Predicates on Floats
196 @section Predicates on Floats
199 This section describes some miscellaneous test functions on doubles.
200 Prototypes for these functions appear in @file{math.h}. These are BSD
201 functions, and thus are available if you define @code{_BSD_SOURCE} or
206 @deftypefun int isinf (double @var{x})
207 @deftypefunx int isinff (float @var{x})
208 @deftypefunx int isinfl (long double @var{x})
209 This function returns @code{-1} if @var{x} represents negative infinity,
210 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
215 @deftypefun int isnan (double @var{x})
216 @deftypefunx int isnanf (float @var{x})
217 @deftypefunx int isnanl (long double @var{x})
218 This function returns a nonzero value if @var{x} is a ``not a number''
219 value, and zero otherwise. (You can just as well use @code{@var{x} !=
220 @var{x}} to get the same result).
222 However, @code{isnan} will not raise an invalid exception if @var{x} is
223 a signalling NaN, while @code{@var{x} != @var{x}} will. This makes
224 @code{isnan} much slower than the alternative; in code where performance
225 matters and signalling NaNs are unimportant, it's usually better to use
226 @code{@var{x} != @var{x}}, even though this is harder to understand.
232 @deftypefun int finite (double @var{x})
233 @deftypefunx int finitef (float @var{x})
234 @deftypefunx int finitel (long double @var{x})
235 This function returns a nonzero value if @var{x} is finite or a ``not a
236 number'' value, and zero otherwise.
241 @deftypefun double infnan (int @var{error})
242 This function is provided for compatibility with BSD. The other
243 mathematical functions use @code{infnan} to decide what to return on
244 occasion of an error. Its argument is an error code, @code{EDOM} or
245 @code{ERANGE}; @code{infnan} returns a suitable value to indicate this
246 with. @code{-ERANGE} is also acceptable as an argument, and corresponds
247 to @code{-HUGE_VAL} as a value.
249 In the BSD library, on certain machines, @code{infnan} raises a fatal
250 signal in all cases. The GNU library does not do likewise, because that
251 does not fit the @w{ISO C} specification.
254 @strong{Portability Note:} The functions listed in this section are BSD
257 @node Floating-Point Classes
258 @section Floating-Point Number Classification Functions
260 Instead of using the BSD specific functions from the last section it is
261 better to use those in this section which are introduced in the @w{ISO C
262 9X} standard and are therefore widely available.
266 @deftypefn {Macro} int fpclassify (@emph{float-type} @var{x})
267 This is a generic macro which works on all floating-point types and
268 which returns a value of type @code{int}. The possible values are:
272 The floating-point number @var{x} is ``Not a Number'' (@pxref{Not a Number})
274 The value of @var{x} is either plus or minus infinity (@pxref{Infinity})
276 The value of @var{x} is zero. In floating-point formats like @w{IEEE
277 754} where the zero value can be signed this value is also returned if
278 @var{x} is minus zero.
280 Some floating-point formats (such as @w{IEEE 754}) allow floating-point
281 numbers to be represented in a denormalized format. This happens if the
282 absolute value of the number is too small to be represented in the
283 normal format. @code{FP_SUBNORMAL} is returned for such values of @var{x}.
285 This value is returned for all other cases which means the number is a
286 plain floating-point number without special meaning.
289 This macro is useful if more than property of a number must be
290 tested. If one only has to test for, e.g., a NaN value, there are
291 function which are faster.
294 The remainder of this section introduces some more specific functions.
295 They might be implemented faster than the call to @code{fpclassify} and
296 if the actual need in the program is covered be these functions they
297 should be used (and not @code{fpclassify}).
301 @deftypefn {Macro} int isfinite (@emph{float-type} @var{x})
302 The value returned by this macro is nonzero if the value of @var{x} is
303 not plus or minus infinity and not NaN. I.e., it could be implemented as
306 (fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)
309 @code{isfinite} is also implemented as a macro which can handle all
310 floating-point types. Programs should use this function instead of
311 @var{finite} (@pxref{Predicates on Floats}).
316 @deftypefn {Macro} int isnormal (@emph{float-type} @var{x})
317 If @code{isnormal} returns a nonzero value the value or @var{x} is
318 neither a NaN, infinity, zero, nor a denormalized number. I.e., it
319 could be implemented as
322 (fpclassify (x) == FP_NORMAL)
328 @deftypefn {Macro} int isnan (@emph{float-type} @var{x})
329 The situation with this macro is a bit complicated. Here @code{isnan}
330 is a macro which can handle all kinds of floating-point types. It
331 returns a nonzero value is @var{x} does not represent a NaN value and
332 could be written like this
335 (fpclassify (x) == FP_NAN)
338 The complication is that there is a function of the same name and the
339 same semantic defined for compatibility with BSD (@pxref{Predicates on
340 Floats}). Fortunately this should not yield to problems in most cases
341 since the macro and the function have the same semantic. Should in a
342 situation the function be absolutely necessary one can use
349 to avoid the macro expansion. Using the macro has two big advantages:
350 it is more portable and one does not have to choose the right function
351 among @code{isnan}, @code{isnanf}, and @code{isnanl}.
355 @node Operations on Complex
356 @section Projections, Conjugates, and Decomposing of Complex Numbers
357 @cindex project complex numbers
358 @cindex conjugate complex numbers
359 @cindex decompose complex numbers
361 This section lists functions performing some of the simple mathematical
362 operations on complex numbers. Using any of the function requires that
363 the C compiler understands the @code{complex} keyword, introduced to the
364 C language in the @w{ISO C 9X} standard.
367 The prototypes for all functions in this section can be found in
368 @file{complex.h}. All functions are available in three variants, one
369 for each of the three floating-point types.
371 The easiest operation on complex numbers is the decomposition in the
372 real part and the imaginary part. This is done by the next two
377 @deftypefun double creal (complex double @var{z})
378 @deftypefunx float crealf (complex float @var{z})
379 @deftypefunx {long double} creall (complex long double @var{z})
380 These functions return the real part of the complex number @var{z}.
385 @deftypefun double cimag (complex double @var{z})
386 @deftypefunx float cimagf (complex float @var{z})
387 @deftypefunx {long double} cimagl (complex long double @var{z})
388 These functions return the imaginary part of the complex number @var{z}.
392 The conjugate complex value of a given complex number has the same value
393 for the real part but the complex part is negated.
397 @deftypefun {complex double} conj (complex double @var{z})
398 @deftypefunx {complex float} conjf (complex float @var{z})
399 @deftypefunx {complex long double} conjl (complex long double @var{z})
400 These functions return the conjugate complex value of the complex number
406 @deftypefun double carg (complex double @var{z})
407 @deftypefunx float cargf (complex float @var{z})
408 @deftypefunx {long double} cargl (complex long double @var{z})
409 These functions return argument of the complex number @var{z}.
411 Mathematically, the argument is the phase angle of @var{z} with a branch
412 cut along the negative real axis.
417 @deftypefun {complex double} cproj (complex double @var{z})
418 @deftypefunx {complex float} cprojf (complex float @var{z})
419 @deftypefunx {complex long double} cprojl (complex long double @var{z})
420 Return the projection of the complex value @var{z} on the Riemann
421 sphere. Values with a infinite complex part (even if the real part
422 is NaN) are projected to positive infinite on the real axis. If the
423 real part is infinite, the result is equivalent to
426 INFINITY + I * copysign (0.0, cimag (z))
432 @section Absolute Value
433 @cindex absolute value functions
435 These functions are provided for obtaining the @dfn{absolute value} (or
436 @dfn{magnitude}) of a number. The absolute value of a real number
437 @var{x} is @var{x} is @var{x} is positive, @minus{}@var{x} if @var{x} is
438 negative. For a complex number @var{z}, whose real part is @var{x} and
439 whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt
440 (@var{x}*@var{x} + @var{y}*@var{y})}}.
444 Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h};
445 @code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h};
446 @code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}.
450 @deftypefun int abs (int @var{number})
451 This function returns the absolute value of @var{number}.
453 Most computers use a two's complement integer representation, in which
454 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
455 cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined.
460 @deftypefun {long int} labs (long int @var{number})
461 This is similar to @code{abs}, except that both the argument and result
462 are of type @code{long int} rather than @code{int}.
467 @deftypefun {long long int} llabs (long long int @var{number})
468 This is similar to @code{abs}, except that both the argument and result
469 are of type @code{long long int} rather than @code{int}.
471 This function is defined in @w{ISO C 9X}.
476 @deftypefun double fabs (double @var{number})
477 @deftypefunx float fabsf (float @var{number})
478 @deftypefunx {long double} fabsl (long double @var{number})
479 This function returns the absolute value of the floating-point number
485 @deftypefun double cabs (complex double @var{z})
486 @deftypefunx float cabsf (complex float @var{z})
487 @deftypefunx {long double} cabsl (complex long double @var{z})
488 These functions return the absolute value of the complex number @var{z}.
489 The compiler must support complex numbers to use these functions. The
493 sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z}))
496 This function should always be used instead of the direct formula since
497 using the simple straight-forward method can mean to lose accuracy. If
498 one of the squared values is neglectable in size compared to the other
499 value the result should be the same as the larger value. But squaring
500 the value and afterwards using the square root function leads to
501 inaccuracy. See @code{hypot} in @xref{Exponents and Logarithms}.
504 @node Normalization Functions
505 @section Normalization Functions
506 @cindex normalization functions (floating-point)
508 The functions described in this section are primarily provided as a way
509 to efficiently perform certain low-level manipulations on floating point
510 numbers that are represented internally using a binary radix;
511 see @ref{Floating Point Concepts}. These functions are required to
512 have equivalent behavior even if the representation does not use a radix
513 of 2, but of course they are unlikely to be particularly efficient in
517 All these functions are declared in @file{math.h}.
521 @deftypefun double frexp (double @var{value}, int *@var{exponent})
522 @deftypefunx float frexpf (float @var{value}, int *@var{exponent})
523 @deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent})
524 These functions are used to split the number @var{value}
525 into a normalized fraction and an exponent.
527 If the argument @var{value} is not zero, the return value is @var{value}
528 times a power of two, and is always in the range 1/2 (inclusive) to 1
529 (exclusive). The corresponding exponent is stored in
530 @code{*@var{exponent}}; the return value multiplied by 2 raised to this
531 exponent equals the original number @var{value}.
533 For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and
534 stores @code{4} in @code{exponent}.
536 If @var{value} is zero, then the return value is zero and
537 zero is stored in @code{*@var{exponent}}.
542 @deftypefun double ldexp (double @var{value}, int @var{exponent})
543 @deftypefunx float ldexpf (float @var{value}, int @var{exponent})
544 @deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent})
545 These functions return the result of multiplying the floating-point
546 number @var{value} by 2 raised to the power @var{exponent}. (It can
547 be used to reassemble floating-point numbers that were taken apart
550 For example, @code{ldexp (0.8, 4)} returns @code{12.8}.
553 The following functions which come from BSD provide facilities
554 equivalent to those of @code{ldexp} and @code{frexp}:
558 @deftypefun double scalb (double @var{value}, int @var{exponent})
559 @deftypefunx float scalbf (float @var{value}, int @var{exponent})
560 @deftypefunx {long double} scalbl (long double @var{value}, int @var{exponent})
561 The @code{scalb} function is the BSD name for @code{ldexp}.
566 @deftypefun double logb (double @var{x})
567 @deftypefunx float logbf (float @var{x})
568 @deftypefunx {long double} logbl (long double @var{x})
569 These BSD functions return the integer part of the base-2 logarithm of
570 @var{x}, an integer value represented in type @code{double}. This is
571 the highest integer power of @code{2} contained in @var{x}. The sign of
572 @var{x} is ignored. For example, @code{logb (3.5)} is @code{1.0} and
573 @code{logb (4.0)} is @code{2.0}.
575 When @code{2} raised to this power is divided into @var{x}, it gives a
576 quotient between @code{1} (inclusive) and @code{2} (exclusive).
578 If @var{x} is zero, the value is minus infinity (if the machine supports
579 such a value), or else a very small number. If @var{x} is infinity, the
582 The value returned by @code{logb} is one less than the value that
583 @code{frexp} would store into @code{*@var{exponent}}.
586 @node Rounding and Remainders
587 @section Rounding and Remainder Functions
588 @cindex rounding functions
589 @cindex remainder functions
590 @cindex converting floats to integers
593 The functions listed here perform operations such as rounding,
594 truncation, and remainder in division of floating point numbers. Some
595 of these functions convert floating point numbers to integer values.
596 They are all declared in @file{math.h}.
598 You can also convert floating-point numbers to integers simply by
599 casting them to @code{int}. This discards the fractional part,
600 effectively rounding towards zero. However, this only works if the
601 result can actually be represented as an @code{int}---for very large
602 numbers, this is impossible. The functions listed here return the
603 result as a @code{double} instead to get around this problem.
607 @deftypefun double ceil (double @var{x})
608 @deftypefunx float ceilf (float @var{x})
609 @deftypefunx {long double} ceill (long double @var{x})
610 These functions round @var{x} upwards to the nearest integer,
611 returning that value as a @code{double}. Thus, @code{ceil (1.5)}
617 @deftypefun double floor (double @var{x})
618 @deftypefunx float floorf (float @var{x})
619 @deftypefunx {long double} floorl (long double @var{x})
620 These functions round @var{x} downwards to the nearest
621 integer, returning that value as a @code{double}. Thus, @code{floor
622 (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
627 @deftypefun double rint (double @var{x})
628 @deftypefunx float rintf (float @var{x})
629 @deftypefunx {long double} rintl (long double @var{x})
630 These functions round @var{x} to an integer value according to the
631 current rounding mode. @xref{Floating Point Parameters}, for
632 information about the various rounding modes. The default
633 rounding mode is to round to the nearest integer; some machines
634 support other modes, but round-to-nearest is always used unless
635 you explicit select another.
640 @deftypefun double nearbyint (double @var{x})
641 @deftypefunx float nearbyintf (float @var{x})
642 @deftypefunx {long double} nearbyintl (long double @var{x})
643 These functions return the same value as the @code{rint} functions but
644 even some rounding actually takes place @code{nearbyint} does @emph{not}
645 raise the inexact exception.
650 @deftypefun double modf (double @var{value}, double *@var{integer-part})
651 @deftypefunx float modff (float @var{value}, float *@var{integer-part})
652 @deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part})
653 These functions break the argument @var{value} into an integer part and a
654 fractional part (between @code{-1} and @code{1}, exclusive). Their sum
655 equals @var{value}. Each of the parts has the same sign as @var{value},
656 so the rounding of the integer part is towards zero.
658 @code{modf} stores the integer part in @code{*@var{integer-part}}, and
659 returns the fractional part. For example, @code{modf (2.5, &intpart)}
660 returns @code{0.5} and stores @code{2.0} into @code{intpart}.
665 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
666 @deftypefunx float fmodf (float @var{numerator}, float @var{denominator})
667 @deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator})
668 These functions compute the remainder from the division of
669 @var{numerator} by @var{denominator}. Specifically, the return value is
670 @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
671 is the quotient of @var{numerator} divided by @var{denominator}, rounded
672 towards zero to an integer. Thus, @w{@code{fmod (6.5, 2.3)}} returns
673 @code{1.9}, which is @code{6.5} minus @code{4.6}.
675 The result has the same sign as the @var{numerator} and has magnitude
676 less than the magnitude of the @var{denominator}.
678 If @var{denominator} is zero, @code{fmod} fails and sets @code{errno} to
684 @deftypefun double drem (double @var{numerator}, double @var{denominator})
685 @deftypefunx float dremf (float @var{numerator}, float @var{denominator})
686 @deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator})
687 These functions are like @code{fmod} etc except that it rounds the
688 internal quotient @var{n} to the nearest integer instead of towards zero
689 to an integer. For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
690 which is @code{6.5} minus @code{6.9}.
692 The absolute value of the result is less than or equal to half the
693 absolute value of the @var{denominator}. The difference between
694 @code{fmod (@var{numerator}, @var{denominator})} and @code{drem
695 (@var{numerator}, @var{denominator})} is always either
696 @var{denominator}, minus @var{denominator}, or zero.
698 If @var{denominator} is zero, @code{drem} fails and sets @code{errno} to
703 @node Arithmetic on FP Values
704 @section Setting and modifying Single Bits of FP Values
705 @cindex FP arithmetic
707 In certain situations it is too complicated (or expensive) to modify a
708 floating-point value by the normal operations. For a few operations
709 @w{ISO C 9X} defines functions to modify the floating-point value
714 @deftypefun double copysign (double @var{x}, double @var{y})
715 @deftypefunx float copysignf (float @var{x}, float @var{y})
716 @deftypefunx {long double} copysignl (long double @var{x}, long double @var{y})
717 The @code{copysign} function allows to specifiy the sign of the
718 floating-point value given in the parameter @var{x} by discarding the
719 prior content and replacing it with the sign of the value @var{y}.
720 The so found value is returned.
722 This function also works and throws no exception if the parameter
723 @var{x} is a @code{NaN}. If the platform supports the signed zero
724 representation @var{x} might also be zero.
726 This function is defined in @w{IEC 559} (and the appendix with
727 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
732 @deftypefun int signbit (@emph{float-type} @var{x})
733 @code{signbit} is a generic macro which can work on all floating-point
734 types. It returns a nonzero value if the value of @var{x} has its sign
737 This is not the same as @code{x < 0.0} since in some floating-point
738 formats (e.g., @w{IEEE 754}) the zero value is optionally signed. The
739 comparison @code{-0.0 < 0.0} will not be true while @code{signbit
740 (-0.0)} will return a nonzero value.
745 @deftypefun double nextafter (double @var{x}, double @var{y})
746 @deftypefunx float nextafterf (float @var{x}, float @var{y})
747 @deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y})
748 The @code{nextafter} function returns the next representable neighbor of
749 @var{x} in the direction towards @var{y}. Depending on the used data
750 type the steps make have a different size. If @math{@var{x} = @var{y}}
751 the function simply returns @var{x}. If either value is a @code{NaN}
752 one the @code{NaN} values is returned. Otherwise a value corresponding
753 to the value of the least significant bit in the mantissa is
754 added/subtracted (depending on the direction). If the resulting value
755 is not finite but @var{x} is, overflow is signaled. Underflow is
756 signaled if the resulting value is a denormalized number (if the @w{IEEE
757 754}/@w{IEEE 854} representation is used).
759 This function is defined in @w{IEC 559} (and the appendix with
760 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
766 @deftypefun double nan (const char *@var{tagp})
767 @deftypefunx float nanf (const char *@var{tagp})
768 @deftypefunx {long double} nanl (const char *@var{tagp})
769 The @code{nan} function returns a representation of the NaN value. If
770 quiet NaNs are supported by the platform a call like @code{nan
771 ("@var{n-char-sequence}")} is equivalent to @code{strtod
772 ("NAN(@var{n-char-sequence})")}. The exact implementation is left
773 unspecified but on systems using IEEE arithmethic the
774 @var{n-char-sequence} specifies the bits of the mantissa for the NaN
779 @node Special arithmetic on FPs
780 @section Special Arithmetic on FPs
781 @cindex positive difference
785 A frequent operation of numbers is the determination of mimuma, maxima,
786 or the difference between numbers. The @w{ISO C 9X} standard introduces
787 three functions which implement this efficiently while also providing
788 some useful functions which is not so efficient to implement. Machine
789 specific implementation might perform this very efficient.
793 @deftypefun double fmin (double @var{x}, double @var{y})
794 @deftypefunx float fminf (float @var{x}, float @var{y})
795 @deftypefunx {long double} fminl (long double @var{x}, long double @var{y})
796 The @code{fmin} function determine the minimum of the two values @var{x}
797 and @var{y} and returns it.
799 If an argument is NaN it as treated as missing and the other value is
800 returned. If both values are NaN one of the values is returned.
805 @deftypefun double fmax (double @var{x}, double @var{y})
806 @deftypefunx float fmaxf (float @var{x}, float @var{y})
807 @deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y})
808 The @code{fmax} function determine the maximum of the two values @var{x}
809 and @var{y} and returns it.
811 If an argument is NaN it as treated as missing and the other value is
812 returned. If both values are NaN one of the values is returned.
817 @deftypefun double fdim (double @var{x}, double @var{y})
818 @deftypefunx float fdimf (float @var{x}, float @var{y})
819 @deftypefunx {long double} fdiml (long double @var{x}, long double @var{y})
820 The @code{fdim} function computes the positive difference between
821 @var{x} and @var{y} and returns this value. @dfn{Positive difference}
822 means that if @var{x} is greater than @var{y} the value @math{@var{x} -
823 @var{y}} is returned. Otherwise the return value is @math{+0}.
825 If any of the arguments is NaN this value is returned. If both values
826 are NaN, one of the values is returned.
831 @deftypefun double fma (double @var{x}, double @var{y}, double @var{z})
832 @deftypefunx float fmaf (float @var{x}, float @var{y}, float @var{z})
833 @deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z})
835 The name of the function @code{fma} means floating-point multiply-add.
836 I.e., the operation performed is @math{(@var{x} @mul{} @var{y}) +
837 @var{z}}. The speciality of this function is that the intermediate
838 result is not rounded and the addition is performed with the full
839 precision of the multiplcation.
841 This function was introduced because some processors provide such a
842 function in their FPU implementation. Since compilers cannot optimize
843 code which performs the operation in single steps using this opcode
844 because of rounding differences the operation is available separately so
845 the programmer can select when the rounding of the intermediate result
849 If the @file{math.h} header defines the symbol @code{FP_FAST_FMA} (or
850 @code{FP_FAST_FMAF} and @code{FP_FAST_FMAL} for @code{float} and
851 @code{long double} respectively) the processor typically defines the
852 operation in hardware. The symbols might also be defined if the
853 software implementation is as fast as a multiply and an add but in the
854 GNU C Library the macros indicate hardware support.
858 @node Integer Division
859 @section Integer Division
860 @cindex integer division functions
862 This section describes functions for performing integer division. These
863 functions are redundant in the GNU C library, since in GNU C the @samp{/}
864 operator always rounds towards zero. But in other C implementations,
865 @samp{/} may round differently with negative arguments. @code{div} and
866 @code{ldiv} are useful because they specify how to round the quotient:
867 towards zero. The remainder has the same sign as the numerator.
869 These functions are specified to return a result @var{r} such that the value
870 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
874 To use these facilities, you should include the header file
875 @file{stdlib.h} in your program.
879 @deftp {Data Type} div_t
880 This is a structure type used to hold the result returned by the @code{div}
881 function. It has the following members:
885 The quotient from the division.
888 The remainder from the division.
894 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
895 This function @code{div} computes the quotient and remainder from
896 the division of @var{numerator} by @var{denominator}, returning the
897 result in a structure of type @code{div_t}.
899 If the result cannot be represented (as in a division by zero), the
900 behavior is undefined.
902 Here is an example, albeit not a very useful one.
906 result = div (20, -6);
910 Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
915 @deftp {Data Type} ldiv_t
916 This is a structure type used to hold the result returned by the @code{ldiv}
917 function. It has the following members:
921 The quotient from the division.
924 The remainder from the division.
927 (This is identical to @code{div_t} except that the components are of
928 type @code{long int} rather than @code{int}.)
933 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
934 The @code{ldiv} function is similar to @code{div}, except that the
935 arguments are of type @code{long int} and the result is returned as a
936 structure of type @code{ldiv_t}.
941 @deftp {Data Type} lldiv_t
942 This is a structure type used to hold the result returned by the @code{lldiv}
943 function. It has the following members:
946 @item long long int quot
947 The quotient from the division.
949 @item long long int rem
950 The remainder from the division.
953 (This is identical to @code{div_t} except that the components are of
954 type @code{long long int} rather than @code{int}.)
959 @deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator})
960 The @code{lldiv} function is like the @code{div} function, but the
961 arguments are of type @code{long long int} and the result is returned as
962 a structure of type @code{lldiv_t}.
964 The @code{lldiv} function is a GNU extension but it will eventually be
965 part of the next ISO C standard.
969 @node Parsing of Numbers
970 @section Parsing of Numbers
971 @cindex parsing numbers (in formatted input)
972 @cindex converting strings to numbers
973 @cindex number syntax, parsing
974 @cindex syntax, for reading numbers
976 This section describes functions for ``reading'' integer and
977 floating-point numbers from a string. It may be more convenient in some
978 cases to use @code{sscanf} or one of the related functions; see
979 @ref{Formatted Input}. But often you can make a program more robust by
980 finding the tokens in the string by hand, then converting the numbers
984 * Parsing of Integers:: Functions for conversion of integer values.
985 * Parsing of Floats:: Functions for conversion of floating-point
989 @node Parsing of Integers
990 @subsection Parsing of Integers
993 These functions are declared in @file{stdlib.h}.
997 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
998 The @code{strtol} (``string-to-long'') function converts the initial
999 part of @var{string} to a signed integer, which is returned as a value
1000 of type @code{long int}.
1002 This function attempts to decompose @var{string} as follows:
1006 A (possibly empty) sequence of whitespace characters. Which characters
1007 are whitespace is determined by the @code{isspace} function
1008 (@pxref{Classification of Characters}). These are discarded.
1011 An optional plus or minus sign (@samp{+} or @samp{-}).
1014 A nonempty sequence of digits in the radix specified by @var{base}.
1016 If @var{base} is zero, decimal radix is assumed unless the series of
1017 digits begins with @samp{0} (specifying octal radix), or @samp{0x} or
1018 @samp{0X} (specifying hexadecimal radix); in other words, the same
1019 syntax used for integer constants in C.
1021 Otherwise @var{base} must have a value between @code{2} and @code{35}.
1022 If @var{base} is @code{16}, the digits may optionally be preceded by
1023 @samp{0x} or @samp{0X}. If base has no legal value the value returned
1024 is @code{0l} and the global variable @code{errno} is set to @code{EINVAL}.
1027 Any remaining characters in the string. If @var{tailptr} is not a null
1028 pointer, @code{strtol} stores a pointer to this tail in
1029 @code{*@var{tailptr}}.
1032 If the string is empty, contains only whitespace, or does not contain an
1033 initial substring that has the expected syntax for an integer in the
1034 specified @var{base}, no conversion is performed. In this case,
1035 @code{strtol} returns a value of zero and the value stored in
1036 @code{*@var{tailptr}} is the value of @var{string}.
1038 In a locale other than the standard @code{"C"} locale, this function
1039 may recognize additional implementation-dependent syntax.
1041 If the string has valid syntax for an integer but the value is not
1042 representable because of overflow, @code{strtol} returns either
1043 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as
1044 appropriate for the sign of the value. It also sets @code{errno}
1045 to @code{ERANGE} to indicate there was overflow.
1047 Because the value @code{0l} is a correct result for @code{strtol} the
1048 user who is interested in handling errors should set the global variable
1049 @code{errno} to @code{0} before calling this function, so that the program
1050 can later test whether an error occurred.
1052 There is an example at the end of this section.
1057 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
1058 The @code{strtoul} (``string-to-unsigned-long'') function is like
1059 @code{strtol} except it deals with unsigned numbers, and returns its
1060 value with type @code{unsigned long int}. If the number has a leading
1061 @samp{-} sign the negated value is returned. The syntax is the same as
1062 described above for @code{strtol}. The value returned in case of
1063 overflow is @code{ULONG_MAX} (@pxref{Range of Type}).
1065 Like @code{strtol} this function sets @code{errno} and returns the value
1066 @code{0ul} in case the value for @var{base} is not in the legal range.
1071 @deftypefun {long long int} strtoll (const char *@var{string}, char **@var{tailptr}, int @var{base})
1072 The @code{strtoll} function is like @code{strtol} except that is deals
1073 with extra long numbers and it returns its value with type @code{long
1076 If the string has valid syntax for an integer but the value is not
1077 representable because of overflow, @code{strtoll} returns either
1078 @code{LONG_LONG_MAX} or @code{LONG_LONG_MIN} (@pxref{Range of Type}), as
1079 appropriate for the sign of the value. It also sets @code{errno} to
1080 @code{ERANGE} to indicate there was overflow.
1082 The @code{strtoll} function is a GNU extension but it will eventually be
1083 part of the next ISO C standard.
1088 @deftypefun {long long int} strtoq (const char *@var{string}, char **@var{tailptr}, int @var{base})
1089 @code{strtoq} (``string-to-quad-word'') is only an commonly used other
1090 name for the @code{strtoll} function. Everything said for
1091 @code{strtoll} applies to @code{strtoq} as well.
1096 @deftypefun {unsigned long long int} strtoull (const char *@var{string}, char **@var{tailptr}, int @var{base})
1097 The @code{strtoull} function is like @code{strtoul} except that is deals
1098 with extra long numbers and it returns its value with type
1099 @code{unsigned long long int}. The value returned in case of overflow
1100 is @code{ULONG_LONG_MAX} (@pxref{Range of Type}).
1102 The @code{strtoull} function is a GNU extension but it will eventually be
1103 part of the next ISO C standard.
1108 @deftypefun {unsigned long long int} strtouq (const char *@var{string}, char **@var{tailptr}, int @var{base})
1109 @code{strtouq} (``string-to-unsigned-quad-word'') is only an commonly
1110 used other name for the @code{strtoull} function. Everything said for
1111 @code{strtoull} applies to @code{strtouq} as well.
1116 @deftypefun {long int} atol (const char *@var{string})
1117 This function is similar to the @code{strtol} function with a @var{base}
1118 argument of @code{10}, except that it need not detect overflow errors.
1119 The @code{atol} function is provided mostly for compatibility with
1120 existing code; using @code{strtol} is more robust.
1125 @deftypefun int atoi (const char *@var{string})
1126 This function is like @code{atol}, except that it returns an @code{int}
1127 value rather than @code{long int}. The @code{atoi} function is also
1128 considered obsolete; use @code{strtol} instead.
1133 @deftypefun {long long int} atoll (const char *@var{string})
1134 This function is similar to @code{atol}, except it returns a @code{long
1135 long int} value rather than @code{long int}.
1137 The @code{atoll} function is a GNU extension but it will eventually be
1138 part of the next ISO C standard.
1141 The POSIX locales contain some information about how to format numbers
1142 (@pxref{General Numeric}). This mainly deals with representing numbers
1143 for better readability for humans. The functions present so far in this
1144 section cannot handle numbers in this form.
1146 If this functionality is needed in a program one can use the functions
1147 from the @code{scanf} family which know about the flag @samp{'} for
1148 parsing numeric input (@pxref{Numeric Input Conversions}). Sometimes it
1149 is more desirable to have finer control.
1151 In these situation one could use the function
1152 @code{__strto@var{XXX}_internal}. @var{XXX} here stands for any of the
1153 above forms. All numeric conversion functions (including the functions
1154 to process floating-point numbers) have such a counterpart. The
1155 difference to the normal form is the extra argument at the end of the
1156 parameter list. If this value has an non-zero value the handling of
1157 number grouping is enabled. The advantage of using these functions is
1158 that the @var{tailptr} parameters allow to determine which part of the
1159 input is processed. The @code{scanf} functions don't provide this
1160 information. The drawback of using these functions is that they are not
1161 portable. They only exist in the GNU C library.
1164 Here is a function which parses a string as a sequence of integers and
1165 returns the sum of them:
1169 sum_ints_from_string (char *string)
1177 /* @r{Skip whitespace by hand, to detect the end.} */
1178 while (isspace (*string)) string++;
1182 /* @r{There is more nonwhitespace,} */
1183 /* @r{so it ought to be another number.} */
1186 next = strtol (string, &tail, 0);
1187 /* @r{Add it in, if not overflow.} */
1189 printf ("Overflow\n");
1192 /* @r{Advance past it.} */
1200 @node Parsing of Floats
1201 @subsection Parsing of Floats
1204 These functions are declared in @file{stdlib.h}.
1208 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
1209 The @code{strtod} (``string-to-double'') function converts the initial
1210 part of @var{string} to a floating-point number, which is returned as a
1211 value of type @code{double}.
1213 This function attempts to decompose @var{string} as follows:
1217 A (possibly empty) sequence of whitespace characters. Which characters
1218 are whitespace is determined by the @code{isspace} function
1219 (@pxref{Classification of Characters}). These are discarded.
1222 An optional plus or minus sign (@samp{+} or @samp{-}).
1225 A nonempty sequence of digits optionally containing a decimal-point
1226 character---normally @samp{.}, but it depends on the locale
1227 (@pxref{Numeric Formatting}).
1230 An optional exponent part, consisting of a character @samp{e} or
1231 @samp{E}, an optional sign, and a sequence of digits.
1234 Any remaining characters in the string. If @var{tailptr} is not a null
1235 pointer, a pointer to this tail of the string is stored in
1236 @code{*@var{tailptr}}.
1239 If the string is empty, contains only whitespace, or does not contain an
1240 initial substring that has the expected syntax for a floating-point
1241 number, no conversion is performed. In this case, @code{strtod} returns
1242 a value of zero and the value returned in @code{*@var{tailptr}} is the
1243 value of @var{string}.
1245 In a locale other than the standard @code{"C"} or @code{"POSIX"} locales,
1246 this function may recognize additional locale-dependent syntax.
1248 If the string has valid syntax for a floating-point number but the value
1249 is not representable because of overflow, @code{strtod} returns either
1250 positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
1251 the sign of the value. Similarly, if the value is not representable
1252 because of underflow, @code{strtod} returns zero. It also sets @code{errno}
1253 to @code{ERANGE} if there was overflow or underflow.
1255 There are two more special inputs which are recognized by @code{strtod}.
1256 The string @code{"inf"} or @code{"infinity"} (without consideration of
1257 case and optionally preceded by a @code{"+"} or @code{"-"} sign) is
1258 changed to the floating-point value for infinity if the floating-point
1259 format supports this; and to the largest representable value otherwise.
1261 If the input string is @code{"nan"} or
1262 @code{"nan(@var{n-char-sequence})"} the return value of @code{strtod} is
1263 the representation of the NaN (not a number) value (if the
1264 floating-point format supports this). In the second form the part
1265 @var{n-char-sequence} allows to specify the form of the NaN value in an
1266 implementation specific way. When using the @w{IEEE 754}
1267 floating-point format, the NaN value can have a lot of forms since only
1268 at least one bit in the mantissa must be set. In the GNU C library
1269 implementation of @code{strtod} the @var{n-char-sequence} is interpreted
1270 as a number (as recognized by @code{strtol}, @pxref{Parsing of Integers}).
1271 The mantissa of the return value corresponds to this given number.
1273 Since the value zero which is returned in the error case is also a valid
1274 result the user should set the global variable @code{errno} to zero
1275 before calling this function. So one can test for failures after the
1276 call since all failures set @code{errno} to a non-zero value.
1281 @deftypefun float strtof (const char *@var{string}, char **@var{tailptr})
1282 This function is similar to the @code{strtod} function but it returns a
1283 @code{float} value instead of a @code{double} value. If the precision
1284 of a @code{float} value is sufficient this function should be used since
1285 it is much faster than @code{strtod} on some architectures. The reasons
1286 are obvious: @w{IEEE 754} defines @code{float} to have a mantissa of 23
1287 bits while @code{double} has 53 bits and every additional bit of
1288 precision can require additional computation.
1290 If the string has valid syntax for a floating-point number but the value
1291 is not representable because of overflow, @code{strtof} returns either
1292 positive or negative @code{HUGE_VALF} (@pxref{Mathematics}), depending on
1293 the sign of the value.
1295 This function is a GNU extension.
1300 @deftypefun {long double} strtold (const char *@var{string}, char **@var{tailptr})
1301 This function is similar to the @code{strtod} function but it returns a
1302 @code{long double} value instead of a @code{double} value. It should be
1303 used when high precision is needed. On systems which define a @code{long
1304 double} type (i.e., on which it is not the same as @code{double})
1305 running this function might take significantly more time since more bits
1306 of precision are required.
1308 If the string has valid syntax for a floating-point number but the value
1309 is not representable because of overflow, @code{strtold} returns either
1310 positive or negative @code{HUGE_VALL} (@pxref{Mathematics}), depending on
1311 the sign of the value.
1313 This function is a GNU extension.
1316 As for the integer parsing functions there are additional functions
1317 which will handle numbers represented using the grouping scheme of the
1318 current locale (@pxref{Parsing of Integers}).
1322 @deftypefun double atof (const char *@var{string})
1323 This function is similar to the @code{strtod} function, except that it
1324 need not detect overflow and underflow errors. The @code{atof} function
1325 is provided mostly for compatibility with existing code; using
1326 @code{strtod} is more robust.
1330 @node Old-style number conversion
1331 @section Old-style way of converting numbers to strings
1333 The @w{System V} library provided three functions to convert numbers to
1334 strings which have a unusual and hard-to-be-used semantic. The GNU C
1335 library also provides these functions together with some useful
1336 extensions in the same sense.
1338 Generally, you should avoid using these functions unless the really fit
1339 into the problem you have to to solve. Otherwise it is almost always
1340 better to use @code{sprintf} since its greater availability (it is an
1341 @w{ISO C} function).
1345 @comment SVID, Unix98
1346 @deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{sign})
1347 The function @code{ecvt} converts the floating-point number @var{value}
1348 to a string with at most @var{ndigit} decimal digits. If @code{ndigit}
1349 is greater than the accuracy of the @code{double} floating-point type
1350 the implementation can shorten @var{ndigit} to a reasonable value. The
1351 returned string neither contains decimal point nor sign. The high-order
1352 digit of the string is non-zero (unless @var{value} is actually zero)
1353 and the low-order digit is rounded. The variable pointed to by
1354 @var{decpt} gets the position of the decimal character relative to the
1355 start of the string. If @var{value} is negative, @var{sign} is set to a
1356 non-zero value, otherwise to 0.
1358 The returned string is statically allocated and overwritten by each call
1361 If @var{value} is zero, it's implementation defined if @var{decpt} is
1362 @code{0} or @code{1}.
1364 The prototype for this function can be found in @file{stdlib.h}.
1367 As an example @code{ecvt (12.3, 5, &decpt, &sign)} returns @code{"12300"}
1368 and sets @var{decpt} to @code{2} and @var{sign} to @code{0}.
1371 @comment SVID, Unix98
1372 @deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int @var{decpt}, int *@var{sign})
1373 The function @code{fcvt} is similar to @code{ecvt} with the difference
1374 that @var{ndigit} specifies the digits after the decimal point. If
1375 @var{ndigit} is less than zero, @var{value} is rounded to the left of
1376 the decimal point upto the reasonable limit (e.g., @math{123.45} is only
1377 rounded to the third digit before the decimal point, even if
1378 @var{ndigit} is less than @math{-3}).
1380 The returned string is statically allocated and overwritten by each call
1383 The prototype for this function can be found in @file{stdlib.h}.
1387 @comment SVID, Unix98
1388 @deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf})
1389 The @code{gcvt} function also converts @var{value} to a NUL terminated
1390 string but in a way similar to the @code{%g} format of
1391 @code{sprintf}. It also does not use a static buffer but instead uses
1392 the user-provided buffer starting at @var{buf}. It is the user's
1393 responsibility to make sure the buffer is long enough to contain the
1394 result. Unlike the @code{ecvt} and @code{fcvt} functions @code{gcvt}
1395 includes the sign and the decimal point characters (which are determined
1396 according to the current locale) in the result. Therefore there are yet
1397 less reasons to use this function instead of @code{sprintf}.
1399 The return value is @var{buf}.
1401 The prototype for this function can be found in @file{stdlib.h}.
1405 All three functions have in common that they use @code{double}
1406 values as parameter. Calling these functions using @code{long
1407 double} values would mean a loss of precision due to the implicit
1408 rounding. Therefore the GNU C library contains three more functions
1409 with similar semantics which take @code{long double} values.
1413 @deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{sign})
1414 This function is equivalent to the @code{ecvt} function except that it
1415 takes an @code{long double} value for the first parameter.
1417 This function is a GNU extension. The prototype can be found in
1423 @deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int @var{decpt}, int *@var{sign})
1424 This function is equivalent to the @code{fcvt} function except that it
1425 takes an @code{long double} value for the first parameter.
1427 This function is a GNU extension. The prototype can be found in
1433 @deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf})
1434 This function is equivalent to the @code{gcvt} function except that it
1435 takes an @code{long double} value for the first parameter.
1437 This function is a GNU extension. The prototype can be found in
1443 As said above the @code{ecvt} and @code{fcvt} function along with their
1444 @code{long double} equivalents have the problem that they return a value
1445 located in a static buffer which is overwritten by the next call of the
1446 function. This limitation is lifted in yet another set of functions
1447 which also are GNU extensions. These reentrant functions can be
1448 recognized by the by the conventional @code{_r} ending. Obviously there
1449 is no need for a @code{gcvt_r} function.
1453 @deftypefun {char *} ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{sign}, char *@var{buf}, size_t @var{len})
1454 The @code{ecvt_r} function is similar to the @code{ecvt} function except
1455 that it places its result into the user-specified buffer starting at
1456 @var{buf} with length @var{len}.
1458 This function is a GNU extension. The prototype can be found in
1463 @comment SVID, Unix98
1464 @deftypefun {char *} fcvt_r (double @var{value}, int @var{ndigit}, int @var{decpt}, int *@var{sign}, char *@var{buf}, size_t @var{len})
1465 The @code{fcvt_r} function is similar to the @code{fcvt} function except
1466 that it places its result into the user-specified buffer starting at
1467 @var{buf} with length @var{len}.
1469 This function is a GNU extension. The prototype can be found in
1475 @deftypefun {char *} qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{sign}, char *@var{buf}, size_t @var{len})
1476 The @code{qecvt_r} function is similar to the @code{qecvt} function except
1477 that it places its result into the user-specified buffer starting at
1478 @var{buf} with length @var{len}.
1480 This function is a GNU extension. The prototype can be found in
1486 @deftypefun {char *} qfcvt_r (long double @var{value}, int @var{ndigit}, int @var{decpt}, int *@var{sign}, char *@var{buf}, size_t @var{len})
1487 The @code{qfcvt_r} function is similar to the @code{qfcvt} function except
1488 that it places its result into the user-specified buffer starting at
1489 @var{buf} with length @var{len}.
1491 This function is a GNU extension. The prototype can be found in