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 2020-11-01 "Linux" "Linux Programmer's Manual"
  46 .SH NAME
  47 strtod, strtof, strtold \- convert ASCII string to floating-point number
  48 .SH SYNOPSIS
  49 .nf
  50 .B #include <stdlib.h>
  51 .PP
  52 .BI "double strtod(const char *" nptr ", char **" endptr );
  53 .BI "float strtof(const char *" nptr ", char **" endptr );
  54 .BI "long double strtold(const char *" nptr ", char **" endptr );
  55 .fi
  56 .PP
  57 .RS -4
  58 Feature Test Macro Requirements for glibc (see
  59 .BR feature_test_macros (7)):
  60 .RE
  61 .PP
  62 .BR strtof (),
  63 .BR strtold ():
  64 .nf
  65     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  66 .fi
  67 .SH DESCRIPTION
  68 The
  69 .BR strtod (),
  70 .BR strtof (),
  71 and
  72 .BR strtold ()
  73 functions convert the initial portion of the string pointed to by
  74 .I nptr
  75 to
  76 .IR double ,
  77 .IR float ,
  78 and
  79 .I long double
  80 representation, respectively.
  81 .PP
  82 The expected form of the (initial portion of the) string is
  83 optional leading white space as recognized by
  84 .BR isspace (3),
  85 an optional plus (\(aq+\(aq) or minus sign (\(aq\-\(aq) and then either
  86 (i) a decimal number, or (ii) a hexadecimal number,
  87 or (iii) an infinity, or (iv) a NAN (not-a-number).
  88 .PP
  89 A
  90 .I "decimal number"
  91 consists of a nonempty sequence of decimal digits
  92 possibly containing a radix character (decimal point, locale-dependent,
  93 usually \(aq.\(aq), optionally followed by a decimal exponent.
  94 A decimal exponent consists of an \(aqE\(aq or \(aqe\(aq, followed by an
  95 optional plus or minus sign, followed by a nonempty sequence of
  96 decimal digits, and indicates multiplication by a power of 10.
  97 .PP
  98 A
  99 .I "hexadecimal number"
 100 consists of a "0x" or "0X" followed by a nonempty sequence of
 101 hexadecimal digits possibly containing a radix character,
 102 optionally followed by a binary exponent.
 103 A binary exponent
 104 consists of a \(aqP\(aq or \(aqp\(aq, followed by an optional
 105 plus or minus sign, followed by a nonempty sequence of
 106 decimal digits, and indicates multiplication by a power of 2.
 107 At least one of radix character and binary exponent must be present.
 108 .PP
 109 An
 110 .I infinity
 111 is either "INF" or "INFINITY", disregarding case.
 112 .PP
 113 A
 114 .I NAN
 115 is "NAN" (disregarding case) optionally followed by a string,
 116 .IR (n-char-sequence) ,
 117 where
 118 .IR n-char-sequence
 119 specifies in an implementation-dependent
 120 way the type of NAN (see NOTES).
 121 .SH RETURN VALUE
 122 These functions return the converted value, if any.
 123 .PP
 124 If
 125 .I endptr
 126 is not NULL,
 127 a pointer to the character after the last character used in the conversion
 128 is stored in the location referenced by
 129 .IR endptr .
 130 .PP
 131 If no conversion is performed, zero is returned and (unless
 132 .I endptr
 133 is null) the value of
 134 .I nptr
 135 is stored in the location referenced by
 136 .IR endptr .
 137 .PP
 138 If the correct value would cause overflow, plus or minus
 139 .BR HUGE_VAL ,
 140 .BR HUGE_VALF ,
 141 or
 142 .B HUGE_VALL
 143 is returned (according to the return type and sign of the value),
 144 and
 145 .B ERANGE
 146 is stored in
 147 .IR errno .
 148 .PP
 149 If the correct value would cause underflow,
 150 a value with magnitude no larger than
 151 .BR DBL_MIN ,
 152 .BR FLT_MIN ,
 153 or
 154 .B LDBL_MIN
 155 is returned and
 156 .B ERANGE
 157 is stored in
 158 .IR errno .
 159 .SH ERRORS
 160 .TP
 161 .B ERANGE
 162 Overflow or underflow occurred.
 163 .SH ATTRIBUTES
 164 For an explanation of the terms used in this section, see
 165 .BR attributes (7).
 166 .ad l
 167 .nh
 168 .TS
 169 allbox;
 170 lbx lb lb
 171 l l l.
 172 Interface       Attribute       Value
 173 T{
 174 .BR strtod (),
 175 .BR strtof (),
 176 .BR strtold ()
 177 T}      Thread safety   MT-Safe locale
 178 .TE
 179 .hy
 180 .ad
 181 .sp 1
 182 .SH CONFORMING TO
 183 POSIX.1-2001, POSIX.1-2008, C99.
 184 .PP
 185 .BR strtod ()
 186 was also described in C89.
 187 .SH NOTES
 188 Since
 189 0 can legitimately be returned
 190 on both success and failure, the calling program should set
 191 .I errno
 192 to 0 before the call,
 193 and then determine if an error occurred by checking whether
 194 .I errno
 195 has a nonzero value after the call.
 196 .PP
 197 In the glibc implementation, the
 198 .IR n-char-sequence
 199 that optionally follows "NAN"
 200 is interpreted as an integer number
 201 (with an optional '0' or '0x' prefix to select base 8 or 16)
 202 that is to be placed in the
 203 mantissa component of the returned value.
 204 .\" From glibc 2.8's stdlib/strtod_l.c:
 205 .\"     We expect it to be a number which is put in the
 206 .\"     mantissa of the number.
 207 .\" It looks as though at least FreeBSD (according to the manual) does
 208 .\" something similar.
 209 .\" C11 says: "An implementation may use the n-char sequence to determine
 210 .\"     extra information to be represented in the NaN's significant."
 211 .SH EXAMPLES
 212 See the example on the
 213 .BR strtol (3)
 214 manual page;
 215 the use of the functions described in this manual page is similar.
 216 .SH SEE ALSO
 217 .BR atof (3),
 218 .BR atoi (3),
 219 .BR atol (3),
 220 .BR nan (3),
 221 .BR nanf (3),
 222 .BR nanl (3),
 223 .BR strfromd (3),
 224 .BR strtol (3),
 225 .BR strtoul (3)