ECVT(3P)                                            POSIX Programmer's Manual                                           ECVT(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

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 posi-
       tion 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 (lim-
       ited  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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                      ECVT(3P)