1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   2 .\" Copyright 1989 AT&T.  Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.  Portions Copyright (c) 1992, X/Open Company Limited,  All Rights Reserved.
   3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   4 .\" http://www.opengroup.org/bookstore/.
   5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.
   6 .\"  This notice shall appear on any product containing this material.
   7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  10 .Dd "Jul 19, 2014"
  11 .Dt ECVT 3C
  12 .Os
  13 .Sh NAME
  14 .Nm ecvt, fcvt, gcvt
  15 .Nd convert floating-point number to string
  16 .Sh SYNOPSIS
  17 .In stdlib.h
  18 .Ft "char *"
  19 .Fn ecvt "double value" "int ndigit" "int *restrict decpt" "int *restrict sign"
  20 .Ft "char *"
  21 .Fn fcvt "double value" "int ndigit" "int *restrict decpt" "int *restrict sign"
  22 .Ft "char *"
  23 .Fn gcvt "double value" "int ndigit" "char *buf"
  24 .Sh DESCRIPTION
  25 The
  26 .Fn ecvt ,
  27 .Fn fcvt ,
  28 and
  29 .Fn gcvt
  30 functions convert floating-point numbers to null-terminated strings.
  31 .Ss Fn ecvt
  32 The
  33 .Fn ecvt
  34 function converts
  35 .Fa value
  36 to a null-terminated string of
  37 .Fa ndigit
  38 digits (where
  39 .Fa ndigit
  40 is reduced to an unspecified limit determined by the precision of a
  41 .Ft double
  42 and returns a pointer to the
  43 string.  The high-order digit is non-zero, unless the value is 0.  The
  44 low-order digit is rounded.  The position of the radix character relative to
  45 the beginning of the string is stored in the integer pointed to by
  46 .Fa decpt
  47 (negative means to the left of the returned digits). The radix character is not
  48 included in the returned string. If the sign of the result is negative, the
  49 integer pointed to by
  50 .Fa sign
  51 is non-zero, otherwise it is 0.
  52 .Lp
  53 If the converted value is out of range or is not representable, the contents of
  54 the returned string are unspecified.
  55 .Ss Fn fcvt
  56 The
  57 .Fn fcvt
  58 function is identical to
  59 .Fn ecvt
  60 except that
  61 .Fa ndigit
  62 specifies the number of digits desired after the radix point.  The total number
  63 of digits in the result string is restricted to an unspecified limit as
  64 determined by the precision of a
  65 .Ft double .
  66 .Ss Fn gcvt
  67 The
  68 .Fn gcvt
  69 function converts
  70 .Fa value
  71 to a null-terminated string
  72 (similar to that of the
  73 .Em %g
  74 format of
  75 .Xr printf 3C
  76 in the array pointed to by
  77 .Fa buf
  78 and returns
  79 .Fa buf .
  80 It produces
  81 .Fa ndigit
  82 significant digits (limited to an unspecified value determined by the precision
  83 of a
  84 .Ft double )
  85 in
  86 .Em %f
  87 if possible, or
  88 .Em %e
  89 (scientific notation)
  90 otherwise.  A minus sign is included in the returned string if
  91 .Fa value
  92 is less than 0.  A radix character is included in the returned string if
  93 .Fa value
  94 is not a whole number.  Trailing zeros are suppressed where
  95 .Fa value
  96 is not a whole number.  The radix character is determined by the
  97 .Dv LC_NUMERIC
  98 category of the current locale.  In the default, POSIX, locale, the period
  99 .Pq Em \&.
 100 is used for the radix character.
 101 default locale, POSIX, is used.
 102 .Sh RETURN VALUES
 103 The
 104 .Fn ecvt
 105 and
 106 .Fn fcvt
 107 functions return a pointer to a null-terminated string of digits.
 108 .Lp
 109 The
 110 .Fn gcvt
 111 function returns
 112 .Fa buf .
 113 .Sh ERRORS
 114 No errors are defined.
 115 .Sh USAGE
 116 The return values from
 117 .Fn ecvt
 118 and
 119 .Fn fcvt
 120 might point to
 121 thread-specific data that can be overwritten by subsequent calls to these
 122 functions by the same thread.
 123 .Lp
 124 Portable applications should use
 125 .Xr sprintf 3C ,
 126 which is mandated by
 127 .St -isoC .
 128 .Sh INTERFACE STABILITY
 129 .Sy Obsolete Standard .
 130 .Sh MT-LEVEL
 131 .Sy Safe .
 132 .Sh SEE ALSO
 133 .Xr printf 3C ,
 134 .Xr setlocale 3C
 135 .Xr sprintf 3C ,
 136 .Xr standards 5
 137 .Sh STANDARDS
 138 These functions were introduced in
 139 .St -xpg4.2 .
 140 They were obsoleted in
 141 .St -p1003.1-2001
 142 and removed from
 143 .St -p1003.1-2008 .