stdlib/OpenBSD/ecvt.3

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