NAME

       ecvt, fcvt, gcvt - convert a floating-point number to a string (LEGACY)

SYNOPSIS

       #include <stdlib.h>

       char *ecvt(double value, int ndigit, int *restrict decpt,
              int *restrict sign);
       char *fcvt(double value, int ndigit, int *restrict decpt,
              int *restrict sign);
       char *gcvt(double value, int ndigit, char *buf);

DESCRIPTION

       The  ecvt(),  fcvt(),  and  gcvt() functions shall convert floating-point numbers to null-
       terminated strings.

       The ecvt() function shall convert value to  a  null-terminated  string  of  ndigit  digits
       (where  ndigit is reduced to an unspecified limit determined by the precision of a double)
       and return a pointer to the string. The high-order digit shall  be  non-zero,  unless  the
       value  is 0. The low-order digit shall be rounded in an implementation-defined manner. The
       position of the radix character relative to the beginning of the string shall be stored in
       the  integer  pointed  to by decpt (negative means to the left of the returned digits). If
       value is zero, it is unspecified whether the integer pointed to by decpt would be 0 or  1.
       The  radix  character  shall  not  be  included in the returned string. If the sign of the
       result is negative, the integer pointed to by sign shall be non-zero; otherwise, it  shall
       be 0.

       If  the  converted  value  is  out  of  range or is not representable, the contents of the
       returned string are unspecified.

       The fcvt() function shall be equivalent to ecvt(), except that ndigit specifies the number
       of  digits  desired  after  the  radix character. The total number of digits in the result
       string is restricted to an unspecified limit as determined by the precision of a double.

       The gcvt() function shall convert value to a null-terminated string (similar  to  that  of
       the  %g  conversion  specification  format of printf()) in the array pointed to by buf and
       shall return buf. It shall produce ndigit significant digits (limited  to  an  unspecified
       value  determined  by the precision of a double) in the %f conversion specification format
       of printf() if possible, or the %e conversion specification format of printf() (scientific
       notation)  otherwise.  A  minus  sign shall be included in the returned string if value is
       less than 0. A radix character shall be included in the returned string if value is not  a
       whole  number.   Trailing zeros shall be suppressed where value is not a whole number. The
       radix character is determined by the current locale. If setlocale() has  not  been  called
       successfully,  the default locale, POSIX, is used. The default locale specifies a period (
       '.' ) as the radix character.  The LC_NUMERIC category determines the value of  the  radix
       character within the current locale.

       These  functions need not be reentrant. A function that is not required to be reentrant is
       not required to be thread-safe.

RETURN VALUE

       The ecvt() and fcvt() functions shall return a pointer  to  a  null-terminated  string  of
       digits.

       The gcvt() function shall return buf.

       The return values from ecvt() and fcvt() may point to static data which may be overwritten
       by subsequent calls to these functions.

ERRORS

       No errors are defined.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The sprintf() function is preferred over this function.

RATIONALE

       None.

FUTURE DIRECTIONS

       These functions may be withdrawn in a future version.

SEE ALSO

       printf() , setlocale() , the Base Definitions volume of IEEE Std 1003.1-2001, <stdlib.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .