lib/libc/stdlib/strtod.3

   1 .\"     $NetBSD: strtod.3,v 1.20 2007/10/24 13:42:10 reed Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the American National Standards Committee X3, on Information
   8 .\" Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     from: @(#)strtod.3      8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd March 12, 2006
  37 .Dt STRTOD 3
  38 .Os
  39 .Sh NAME
  40 .Nm strtod ,
  41 .Nm strtof ,
  42 .Nm strtold
  43 .Nd convert
  44 .Tn ASCII
  45 string to double, float, or long double
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In stdlib.h
  50 .Ft double
  51 .Fn strtod "const char * restrict nptr" "char ** restrict endptr"
  52 .Ft float
  53 .Fn strtof "const char * restrict nptr" "char ** restrict endptr"
  54 .Ft long double
  55 .Fn strtold "const char * restrict nptr" "char ** restrict endptr"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn strtod
  59 function converts the initial portion of the string
  60 pointed to by
  61 .Fa nptr
  62 to
  63 .Em double
  64 representation.
  65 .Pp
  66 The
  67 .Fn strtof
  68 function converts the initial portion of the string
  69 pointed to by
  70 .Fa nptr
  71 to
  72 .Em float
  73 representation.
  74 .Pp
  75 The
  76 .Fn strtold
  77 function converts the initial portion of the string
  78 pointed to by
  79 .Fa nptr
  80 to
  81 .Em long double
  82 representation.
  83 .Pp
  84 The expected form of the string is an optional plus
  85 .Pq Sq +
  86 or minus sign
  87 .Pq Sq \-
  88 followed by one of the following:
  89 .Bl -dash
  90 .It
  91 a sequence of digits optionally containing
  92 a decimal-point character, optionally followed by an exponent.
  93 An exponent consists of an
  94 .Sq E
  95 or
  96 .Sq e ,
  97 followed by an optional plus
  98 or minus sign, followed by a sequence of digits.
  99 .It
 100 one of
 101 .Li INF
 102 or
 103 .Li INFINITY ,
 104 ignoring case.
 105 .It
 106 one of
 107 .Li NAN
 108 or
 109 .Li NAN(n-char-sequence-opt) ,
 110 ignoring case.
 111 This implementation currently does not interpret such a sequence.
 112 .El
 113 .Pp
 114 Leading white-space characters in the string (as defined by the
 115 .Xr isspace 3
 116 function) are skipped.
 117 .Sh RETURN VALUES
 118 The
 119 .Fn strtod ,
 120 .Fn strtof ,
 121 and
 122 .Fn strtold
 123 functions return the converted value, if any.
 124 .Pp
 125 A character sequence
 126 .Li INF
 127 or
 128 .Li INFINITY
 129 is converted to \*(If,
 130 if supported, else to the largest finite floating-point number representable
 131 on the machine (i.e.,
 132 .Tn VAX ) .
 133 .Pp
 134 A character sequence
 135 .Li NAN
 136 or
 137 .Li NAN(n-char-sequence-opt)
 138 is converted to a quiet \*(Na, if supported, else remains unrecognized (i.e.,
 139 .Tn VAX ) .
 140 .Pp
 141 If
 142 .Fa endptr
 143 is not
 144 .Dv NULL ,
 145 a pointer to the character after the last character used
 146 in the conversion is stored in the location referenced by
 147 .Fa endptr .
 148 .Pp
 149 If no conversion is performed, zero is returned and the value of
 150 .Fa nptr
 151 is stored in the location referenced by
 152 .Fa endptr .
 153 .Pp
 154 If the correct value would cause overflow, plus or minus
 155 .Dv HUGE_VAL ,
 156 .Dv HUGE_VALF ,
 157 or
 158 .Dv HUGE_VALL
 159 is returned (according to the return type and sign of the value), and
 160 .Dv ERANGE
 161 is stored in
 162 .Va errno .
 163 If the correct value would cause underflow, zero is
 164 returned and
 165 .Dv ERANGE
 166 is stored in
 167 .Va errno .
 168 .Sh ERRORS
 169 .Bl -tag -width Er
 170 .It Bq Er ERANGE
 171 Overflow or underflow occurred.
 172 .El
 173 .Sh SEE ALSO
 174 .Xr atof 3 ,
 175 .Xr atoi 3 ,
 176 .Xr atol 3 ,
 177 .Xr math 3 ,
 178 .Xr strtol 3 ,
 179 .Xr strtoul 3
 180 .Sh STANDARDS
 181 The
 182 .Fn strtod
 183 function
 184 conforms to
 185 .St -ansiC .
 186 The
 187 .Fn strtof
 188 and
 189 .Fn strtold
 190 functions conform to
 191 .St -isoC-99 .
 192 .Sh HISTORY
 193 The
 194 .Fn strtof
 195 and
 196 .Fn strtold
 197 functions appeared in
 198 .Nx 4.0 .