.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "ECVT" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" ecvt 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
ecvt, fcvt, gcvt \- convert a floating-point number to a string (\fBLEGACY\fP)
.SH SYNOPSIS
.LP
\fB#include <stdlib.h>
.br
.sp
char *ecvt(double\fP \fIvalue\fP\fB, int\fP \fIndigit\fP\fB, int *restrict\fP
\fIdecpt\fP\fB,
.br
\ \ \ \ \ \  int *restrict\fP \fIsign\fP\fB);
.br
char *fcvt(double\fP \fIvalue\fP\fB, int\fP \fIndigit\fP\fB, int *restrict\fP
\fIdecpt\fP\fB,
.br
\ \ \ \ \ \  int *restrict\fP \fIsign\fP\fB);
.br
char *gcvt(double\fP \fIvalue\fP\fB, int\fP \fIndigit\fP\fB, char
*\fP\fIbuf\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIecvt\fP(), \fIfcvt\fP(), and \fIgcvt\fP() functions shall convert
floating-point numbers to null-terminated
strings.
.LP
The \fIecvt\fP() function shall convert \fIvalue\fP to a null-terminated
string of \fIndigit\fP digits (where \fIndigit\fP
is reduced to an unspecified limit determined by the precision of
a \fBdouble\fP) 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
\fIdecpt\fP (negative means to the left of the returned digits). If
\fIvalue\fP is zero, it is unspecified whether the integer
pointed to by \fIdecpt\fP 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 \fIsign\fP shall be
non-zero; otherwise, it shall be 0.
.LP
If the converted value is out of range or is not representable, the
contents of the returned string are unspecified.
.LP
The \fIfcvt\fP() function shall be equivalent to \fIecvt\fP(), except
that \fIndigit\fP 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 \fBdouble\fP.
.LP
The \fIgcvt\fP() function shall convert \fIvalue\fP to a null-terminated
string (similar to that of the \fB%g\fP conversion
specification format of \fIprintf\fP()) in the array pointed to by
\fIbuf\fP and shall
return \fIbuf\fP. It shall produce \fIndigit\fP significant digits
(limited to an unspecified value determined by the precision
of a \fBdouble\fP) in the \fB%f\fP conversion specification format
of \fIprintf\fP() if
possible, or the \fB%e\fP conversion specification format of \fIprintf\fP()
(scientific
notation) otherwise. A minus sign shall be included in the returned
string if \fIvalue\fP is less than 0. A radix character shall
be included in the returned string if \fIvalue\fP is not a whole number.
Trailing zeros shall be suppressed where \fIvalue\fP is
not a whole number. The radix character is determined by the current
locale. If \fIsetlocale\fP() has not been called successfully, the
default locale, POSIX, is used. The
default locale specifies a period ( \fB'.'\fP ) as the radix character.
The \fILC_NUMERIC\fP category determines the value of
the radix character within the current locale.
.LP
These functions need not be reentrant. A function that is not required
to be reentrant is not required to be thread-safe.
.SH RETURN VALUE
.LP
The \fIecvt\fP() and \fIfcvt\fP() functions shall return a pointer
to a null-terminated string of digits.
.LP
The \fIgcvt\fP() function shall return \fIbuf\fP.
.LP
The return values from \fIecvt\fP() and \fIfcvt\fP() may point to
static data which may be overwritten by subsequent calls to
these functions.
.SH ERRORS
.LP
No errors are defined.
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
The \fIsprintf\fP() function is preferred over this function.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
These functions may be withdrawn in a future version.
.SH SEE ALSO
.LP
\fIprintf\fP(), \fIsetlocale\fP(), the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<stdlib.h>\fP
.SH 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 .