man3/strtod.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\" %%%LICENSE_END
  37 .\"
  38 .\"     @(#)strtod.3    5.3 (Berkeley) 6/29/91
  39 .\"
  40 .\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu)
  41 .\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt
  42 .\"   (michael@cantor.informatik.rwth-aachen.de)
  43 .\" Added strof, strtold, aeb, 2001-06-07
  44 .\"
  45 .TH STRTOD 3 2017-09-15 "Linux" "Linux Programmer's Manual"
  46 .SH NAME
  47 strtod, strtof, strtold \- convert ASCII string to floating-point number
  48 .SH SYNOPSIS
  49 .B #include <stdlib.h>
  50 .PP
  51 .BI "double strtod(const char *" nptr ", char **" endptr );
  52 .br
  53 .BI "float strtof(const char *" nptr ", char **" endptr );
  54 .br
  55 .BI "long double strtold(const char *" nptr ", char **" endptr );
  56 .PP
  57 .in -4n
  58 Feature Test Macro Requirements for glibc (see
  59 .BR feature_test_macros (7)):
  60 .in
  61 .ad l
  62 .PP
  63 .BR strtof (),
  64 .BR strtold ():
  65 .RS 4
  66 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
  67 .RE
  68 .ad
  69 .SH DESCRIPTION
  70 The
  71 .BR strtod (),
  72 .BR strtof (),
  73 and
  74 .BR strtold ()
  75 functions convert the initial portion of the string pointed to by
  76 .I nptr
  77 to
  78 .IR double ,
  79 .IR float ,
  80 and
  81 .I long double
  82 representation, respectively.
  83 .PP
  84 The expected form of the (initial portion of the) string is
  85 optional leading white space as recognized by
  86 .BR isspace (3),
  87 an optional plus (\(aq+\(aq) or minus sign (\(aq\-\(aq) and then either
  88 (i) a decimal number, or (ii) a hexadecimal number,
  89 or (iii) an infinity, or (iv) a NAN (not-a-number).
  90 .PP
  91 A
  92 .I "decimal number"
  93 consists of a nonempty sequence of decimal digits
  94 possibly containing a radix character (decimal point, locale-dependent,
  95 usually \(aq.\(aq), optionally followed by a decimal exponent.
  96 A decimal exponent consists of an \(aqE\(aq or \(aqe\(aq, followed by an
  97 optional plus or minus sign, followed by a nonempty sequence of
  98 decimal digits, and indicates multiplication by a power of 10.
  99 .PP
 100 A
 101 .I "hexadecimal number"
 102 consists of a "0x" or "0X" followed by a nonempty sequence of
 103 hexadecimal digits possibly containing a radix character,
 104 optionally followed by a binary exponent.
 105 A binary exponent
 106 consists of a \(aqP\(aq or \(aqp\(aq, followed by an optional
 107 plus or minus sign, followed by a nonempty sequence of
 108 decimal digits, and indicates multiplication by a power of 2.
 109 At least one of radix character and binary exponent must be present.
 110 .PP
 111 An
 112 .I infinity
 113 is either "INF" or "INFINITY", disregarding case.
 114 .PP
 115 A
 116 .I NAN
 117 is "NAN" (disregarding case) optionally followed by a string,
 118 .IR (n-char-sequence) ,
 119 where
 120 .IR n-char-sequence
 121 specifies in an implementation-dependent
 122 way the type of NAN (see NOTES).
 123 .SH RETURN VALUE
 124 These functions return the converted value, if any.
 125 .PP
 126 If
 127 .I endptr
 128 is not NULL,
 129 a pointer to the character after the last character used in the conversion
 130 is stored in the location referenced by
 131 .IR endptr .
 132 .PP
 133 If no conversion is performed, zero is returned and (unless
 134 .I endptr
 135 is null) the value of
 136 .I nptr
 137 is stored in the location referenced by
 138 .IR endptr .
 139 .PP
 140 If the correct value would cause overflow, plus or minus
 141 .B HUGE_VAL
 142 .RB ( HUGE_VALF ,
 143 .BR HUGE_VALL )
 144 is returned (according to the sign of the value), and
 145 .B ERANGE
 146 is stored in
 147 .IR errno .
 148 If the correct value would cause underflow, zero is
 149 returned and
 150 .B ERANGE
 151 is stored in
 152 .IR errno .
 153 .SH ERRORS
 154 .TP
 155 .B ERANGE
 156 Overflow or underflow occurred.
 157 .SH ATTRIBUTES
 158 For an explanation of the terms used in this section, see
 159 .BR attributes (7).
 160 .TS
 161 allbox;
 162 lbw29 lb lb
 163 l l l.
 164 Interface       Attribute       Value
 165 T{
 166 .BR strtod (),
 167 .BR strtof (),
 168 .BR strtold ()
 169 T}      Thread safety   MT-Safe locale
 170 .TE
 171 .SH CONFORMING TO
 172 POSIX.1-2001, POSIX.1-2008, C99.
 173 .PP
 174 .BR strtod ()
 175 was also described in C89.
 176 .SH NOTES
 177 Since
 178 0 can legitimately be returned
 179 on both success and failure, the calling program should set
 180 .I errno
 181 to 0 before the call,
 182 and then determine if an error occurred by checking whether
 183 .I errno
 184 has a nonzero value after the call.
 185 .PP
 186 In the glibc implementation, the
 187 .IR n-char-sequence
 188 that optionally follows "NAN"
 189 is interpreted as an integer number
 190 (with an optional '0' or '0x' prefix to select base 8 or 16)
 191 that is to be placed in the
 192 mantissa component of the returned value.
 193 .\" From glibc 2.8's stdlib/strtod_l.c:
 194 .\"     We expect it to be a number which is put in the
 195 .\"     mantissa of the number.
 196 .\" It looks as though at least FreeBSD (according to the manual) does
 197 .\" something similar.
 198 .\" C11 says: "An implementation may use the n-char sequence to determine
 199 .\"     extra information to be represented in the NaN's significant."
 200 .SH EXAMPLES
 201 See the example on the
 202 .BR strtol (3)
 203 manual page;
 204 the use of the functions described in this manual page is similar.
 205 .SH SEE ALSO
 206 .BR atof (3),
 207 .BR atoi (3),
 208 .BR atol (3),
 209 .BR nan (3),
 210 .BR nanf (3),
 211 .BR nanl (3),
 212 .BR strfromd (3),
 213 .BR strtol (3),
 214 .BR strtoul (3)