1.\" $OpenBSD: ecvt.3,v 1.9 2010/04/01 17:06:55 jmc Exp $ 2.\" 3.\" Copyright (c) 2002 Todd C. Miller <Todd.Miller@courtesan.com> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" Sponsored in part by the Defense Advanced Research Projects 18.\" Agency (DARPA) and Air Force Research Laboratory, Air Force 19.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. 20.\" 21.Dd $Mdocdate: April 1 2010 $ 22.Dt ECVT 3 23.Os 24.Sh NAME 25.Nm ecvt , 26.Nm fcvt , 27.Nm gcvt 28.Nd convert double to 29.Tn ASCII 30string 31.Sh SYNOPSIS 32.Fd #include <stdlib.h> 33.Ft char * 34.Fn ecvt "double value" "int ndigit" "int *decpt" "int *sign" 35.Ft char * 36.Fn fcvt "double value" "int ndigit" "int *decpt" "int *sign" 37.Ft char * 38.Fn gcvt "double value" "int ndigit" "char *buf" 39.Sh DESCRIPTION 40.Bf -symbolic 41These functions are provided for compatibility with legacy code. 42New code should use the 43.Xr snprintf 3 44function for improved safety and portability. 45.Ef 46.Pp 47The 48.Fn ecvt , 49.Fn fcvt 50and 51.Fn gcvt 52functions convert the double precision floating-point number 53.Fa value 54to a NUL-terminated 55.Tn ASCII 56string. 57.Pp 58The 59.Fn ecvt 60function converts 61.Fa value 62to a NUL-terminated string of exactly 63.Fa ndigit 64digits and returns a pointer to that string. 65The result is padded with zeroes from left to right as needed. 66There are no leading zeroes unless 67.Fa value 68itself is 0. 69The least significant digit is rounded in an implementation-dependent manner. 70The position of the decimal point relative to the beginning of the string 71is stored in 72.Fa decpt . 73A negative value indicates that the decimal point is located 74to the left of the returned digits (this occurs when there is no 75whole number component to 76.Fa value ) . 77If 78.Fa value 79is zero, it is unspecified whether the integer pointed to by 80.Fa decpt 81will be 0 or 1. 82The decimal point itself is not included in the returned string. 83If the sign of the result is negative, the integer pointed to by 84.Fa sign 85is non-zero; otherwise, it is 0. 86.Pp 87If the converted value is out of range or is not representable, 88the contents of the returned string are unspecified. 89.Pp 90The 91.Fn fcvt 92function is identical to 93.Fn ecvt 94with the exception that 95.Fa ndigit 96specifies the number of digits after the decimal point (zero-padded as 97needed). 98.Pp 99The 100.Fn gcvt 101function converts 102.Fa value 103to a NUL-terminated string similar to the %g 104.Xr printf 3 105format specifier and stores the result in 106.Fa buf . 107It produces 108.Fa ndigit 109significant digits similar to the %f 110.Xr printf 3 111format specifier where possible. 112If 113.Fa ndigit 114does allow sufficient precision, the result is stored in 115exponential notation similar to the %e 116.Xr printf 3 117format specifier. 118If 119.Fa value 120is less than zero, 121.Fa buf 122will be prefixed with a minus sign. 123A decimal point is included in the returned string if 124.Fa value 125is not a whole number. 126Unlike the 127.Fn ecvt 128and 129.Fn fcvt 130functions, 131.Fa buf 132is not zero-padded. 133.Sh RETURN VALUES 134The 135.Fn ecvt , 136.Fn fcvt 137and 138.Fn gcvt 139functions return a NUL-terminated string representation of 140.Fa value . 141.Sh SEE ALSO 142.Xr printf 3 , 143.Xr strtod 3 144.Sh STANDARDS 145The 146.Fn ecvt , 147.Fn fcvt 148and 149.Fn gcvt 150functions conform to 151.St -p1003.1-2001 . 152.Sh CAVEATS 153The 154.Fn ecvt 155and 156.Fn fcvt 157functions return a pointer to internal storage space that will be 158overwritten by subsequent calls to either function. 159.Pp 160The maximum possible precision of the return value is limited by the 161precision of a double and may not be the same on all architectures. 162.Pp 163The 164.Xr snprintf 3 165function is preferred over these functions for new code. 166