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