1ECVT(3P)                   POSIX Programmer's Manual                  ECVT(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

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

SYNOPSIS

15       #include <stdlib.h>
16
17       char *ecvt(double value, int ndigit, int *restrict decpt,
18              int *restrict sign);
19       char *fcvt(double value, int ndigit, int *restrict decpt,
20              int *restrict sign);
21       char *gcvt(double value, int ndigit, char *buf);
22
23

DESCRIPTION

25       The ecvt(), fcvt(), and gcvt() functions shall  convert  floating-point
26       numbers to null-terminated strings.
27
28       The  ecvt() function shall convert value to a null-terminated string of
29       ndigit digits (where ndigit is reduced to an unspecified  limit  deter‐
30       mined by the precision of a double) and return a pointer to the string.
31       The high-order digit shall be non-zero, unless the value is 0. The low-
32       order  digit  shall be rounded in an implementation-defined manner. The
33       position of the radix character relative to the beginning of the string
34       shall  be  stored in the integer pointed to by decpt (negative means to
35       the left of the returned digits). If value is zero, it  is  unspecified
36       whether  the  integer  pointed  to  by decpt would be 0 or 1. The radix
37       character shall not be included in the returned string. If the sign  of
38       the  result  is  negative, the integer pointed to by sign shall be non-
39       zero; otherwise, it shall be 0.
40
41       If the converted value is out of range or  is  not  representable,  the
42       contents of the returned string are unspecified.
43
44       The  fcvt()  function shall be equivalent to ecvt(), except that ndigit
45       specifies the number of digits desired after the radix  character.  The
46       total number of digits in the result string is restricted to an unspec‐
47       ified limit as determined by the precision of a double.
48
49       The gcvt() function shall convert value  to  a  null-terminated  string
50       (similar to that of the %g conversion specification format of printf())
51       in the array pointed to by buf and shall return buf. It  shall  produce
52       ndigit  significant  digits (limited to an unspecified value determined
53       by the precision of a double) in the %f conversion specification format
54       of  printf()  if possible, or the %e conversion specification format of
55       printf()  (scientific  notation)  otherwise.  A  minus  sign  shall  be
56       included  in the returned string if value is less than 0. A radix char‐
57       acter shall be included in the returned string if value is not a  whole
58       number.   Trailing zeros shall be suppressed where value is not a whole
59       number. The radix character is determined by  the  current  locale.  If
60       setlocale()  has  not  been  called  successfully,  the default locale,
61       POSIX, is used. The default locale specifies a period ( '.'  )  as  the
62       radix  character.   The LC_NUMERIC category determines the value of the
63       radix character within the current locale.
64
65       These functions need not be reentrant. A function that is not  required
66       to be reentrant is not required to be thread-safe.
67

RETURN VALUE

69       The ecvt() and fcvt() functions shall return a pointer to a null-termi‐
70       nated string of digits.
71
72       The gcvt() function shall return buf.
73
74       The return values from ecvt() and fcvt() may point to static data which
75       may be overwritten by subsequent calls to these functions.
76

ERRORS

78       No errors are defined.
79
80       The following sections are informative.
81

EXAMPLES

83       None.
84

APPLICATION USAGE

86       The sprintf() function is preferred over this function.
87

RATIONALE

89       None.
90

FUTURE DIRECTIONS

92       These functions may be withdrawn in a future version.
93

SEE ALSO

95       printf(),    setlocale(),    the    Base    Definitions    volume    of
96       IEEE Std 1003.1-2001, <stdlib.h>
97
99       Portions of this text are reprinted and reproduced in  electronic  form
100       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
101       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
102       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
103       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
104       event of any discrepancy between this version and the original IEEE and
105       The Open Group Standard, the original IEEE and The Open Group  Standard
106       is  the  referee document. The original Standard can be obtained online
107       at http://www.opengroup.org/unix/online.html .
108
109
110
111IEEE/The Open Group                  2003                             ECVT(3P)
Impressum