1.\" $OpenBSD: ecvt.3,v 1.13 2019/01/25 00:19:25 millert Exp $ 2.\" 3.\" Copyright (c) 2002 Todd C. Miller <millert@openbsd.org> 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: January 25 2019 $ 22.Dt ECVT 3 23.Os 24.Sh NAME 25.Nm ecvt , 26.Nm fcvt , 27.Nm gcvt 28.Nd convert double to ASCII string 29.Sh SYNOPSIS 30.In stdlib.h 31.Ft char * 32.Fn ecvt "double value" "int ndigit" "int *decpt" "int *sign" 33.Ft char * 34.Fn fcvt "double value" "int ndigit" "int *decpt" "int *sign" 35.Ft char * 36.Fn gcvt "double value" "int ndigit" "char *buf" 37.Sh DESCRIPTION 38.Bf -symbolic 39These functions are provided for compatibility with legacy code. 40New code should use the 41.Xr snprintf 3 42function for improved safety and portability. 43.Ef 44.Pp 45The 46.Fn ecvt , 47.Fn fcvt 48and 49.Fn gcvt 50functions convert the double precision floating-point number 51.Fa value 52to a NUL-terminated 53.Tn ASCII 54string. 55.Pp 56The 57.Fn ecvt 58function converts 59.Fa value 60to a NUL-terminated string of exactly 61.Fa ndigit 62digits and returns a pointer to that string. 63The result is padded with zeroes from left to right as needed. 64There are no leading zeroes unless 65.Fa value 66itself is 0. 67The least significant digit is rounded in an implementation-dependent manner. 68The position of the decimal point relative to the beginning of the string 69is stored in 70.Fa decpt . 71A negative value indicates that the decimal point is located 72to the left of the returned digits (this occurs when there is no 73whole number component to 74.Fa value ) . 75If 76.Fa value 77is zero, it is unspecified whether the integer pointed to by 78.Fa decpt 79will be 0 or 1. 80The decimal point itself is not included in the returned string. 81If the sign of the result is negative, the integer pointed to by 82.Fa sign 83is non-zero; otherwise, it is 0. 84.Pp 85If the converted value is out of range or is not representable, 86the contents of the returned string are unspecified. 87.Pp 88The 89.Fn fcvt 90function is identical to 91.Fn ecvt 92with the exception that 93.Fa ndigit 94specifies the number of digits after the decimal point (zero-padded as 95needed). 96.Pp 97The 98.Fn gcvt 99function converts 100.Fa value 101to a NUL-terminated string similar to the %g 102.Xr printf 3 103format specifier and stores the result in 104.Fa buf . 105It produces 106.Fa ndigit 107significant digits similar to the %f 108.Xr printf 3 109format specifier where possible. 110If 111.Fa ndigit 112does allow sufficient precision, the result is stored in 113exponential notation similar to the %e 114.Xr printf 3 115format specifier. 116If 117.Fa value 118is less than zero, 119.Fa buf 120will be prefixed with a minus sign. 121A decimal point is included in the returned string if 122.Fa value 123is not a whole number. 124Unlike the 125.Fn ecvt 126and 127.Fn fcvt 128functions, 129.Fa buf 130is not zero-padded. 131.Sh RETURN VALUES 132The 133.Fn ecvt , 134.Fn fcvt 135and 136.Fn gcvt 137functions return a NUL-terminated string representation of 138.Fa value . 139.Sh SEE ALSO 140.Xr printf 3 , 141.Xr strtod 3 142.Sh STANDARDS 143The 144.Fn ecvt , 145.Fn fcvt 146and 147.Fn gcvt 148functions conform to 149.St -p1003.1-2001 ; 150as of 151.St -p1003.1-2008 152they are no longer a part of the standard. 153.Sh CAVEATS 154The 155.Fn ecvt 156and 157.Fn fcvt 158functions return a pointer to internal storage space that will be 159overwritten by subsequent calls to either function. 160.Pp 161The maximum possible precision of the return value is limited by the 162precision of a double and may not be the same on all architectures. 163.Pp 164The 165.Xr snprintf 3 166function is preferred over these functions for new code. 167