*** UNIX MANUAL PAGE BROWSER ***

ecvt(3) Library Functions Manual ecvt(3) NAME ecvt, ecvt_r, fcvt, fcvt_r, gcvt - Convert a floating-point number to a string LIBRARY Standard C Library (libc.a) SYNOPSIS #include <stdlib.h> char *ecvt( double value, int num_digits, int *deci- mal_ptr, int *sign); char *fcvt( double value, int num_digits, int *deci- mal_ptr, int *sign); char *gcvt( double value, int num_digits, char *buffer); The following obsolete functions are supported in order to maintain backward compatibility with previous versions of the operating system. You should not use them in new designs. int ecvt_r( double value, int num_digits, int *decimal_ptr, int *sign, char *buffer, int len ); int fcvt_r( double value, int num_digits, int *deci- mal_ptr, int *sign, char *buffer, int len ); PARAMETERS Specifies the double value to be converted. Specifies the number of digits in the resulting string. Holds the position of the decimal point relative to the beginning of the string. A negative number means the decimal point is to the left of the digits given in the string. Holds a value of 0 (zero) if the value is positive or zero, and a nonzero value if it is negative. Specifies the character array to be used as scratch space in calculations and for storing the resulting string. Specifies the length of buffer. Because ecvt temporarily stores intermediate results of its calculations in the buffer, you must specify a len greater than 370. A value of 400 is recommended. DESCRIPTION The ecvt(), fcvt(), and gcvt() functions convert floating-point numbers to null-terminated strings. The ecvt() function converts the value specified by the value parameter to a null-terminated string of length num_digits, and returns a pointer to it. The resulting low-order digit is rounded according to the cur- rent rounding mode. The decimal_ptr parameter is assigned to the posi- tion of the decimal point relative to the position of the string. The sign parameter is assigned a value of 0 (zero) if value is positive or zero, and a nonzero value if value is negative. The decimal point and sign are not included in the string. The fcvt() function is the same as the ecvt() function, except that it rounds to the correct digit for outputting num_digits of digits in C or FORTRAN F-format. In the F-format, num_digits is taken as the number of digits desired after the decimal point. The gcvt() function converts the value specified by the value parameter to a null-terminated string, stores it in the array pointed to by the buffer parameter, and then returns buffer. The gcvt() function at- tempts to produce a string of num_digits significant digits in FORTRAN F-format. If this is not possible, then E-format is used. The string is ready for printing, complete with minus sign, decimal point, or ex- ponent, as appropriate. Trailing zeros are suppressed. In the F-format, num_digits is the number of digits desired after the decimal point. Very large numbers produce a very long string of digits before the decimal point, and then num_digits of digits after the deci- mal point. For large numbers, it is preferable to use the gcvt() or ecvt() function so that the E-format will be used. The ecvt(), fcvt(), and gcvt() functions represent the following spe- cial values that are specified in IEEE Standard 754-1985 for floating- point arithmetic according to the following table. center tab(@); lB l B l l. Value@Representation _ Quiet NaN@NaNQ Signalling NaN@NaNS +Infinity@INF -Infinity@-INF The sign associated with each of these values is stored into the sign parameter. Note, also, that in IEEE floating point operations, a value of 0 (zero) can be positive or negative, as set by the sign parameter. NOTES The ecvt(), fcvt(), and gcvt() functions store the converted string in a thread-specific buffer. Subsequent calls to these functions from the same thread overwrite the contents of the internal buffer. The ecvt_r() and fcvt_r() functions are obsolete reentrant versions of the ecvt() and fcvt() functions. They are supported in order to main- tain backward compatibility with previous versions of the operating system and should not be used in new designs. RETURN VALUES The ecvt(), fcvt(), and gcvt() functions return the converted string. Upon successful completion, the ecvt_r() and fcvt_r() functions store the converted string in the array pointed to by the buffer parameter, and return a value of 0 (zero). Upon failure, these functions return -1 and may set errno. ERRORS If the ecvt_r() or fcvt_r() function fails, errno may be set to the following value: The buffer parameter is invalid or too small. RELATED INFORMATION Functions: atof(3), printf(3), scanf(3). delim off ecvt(3)