man3/strtod.3

   1 '\" t
   2 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to Berkeley by
   6 .\" the American National Standards Committee X3, on Information
   7 .\" Processing Systems.
   8 .\"
   9 .\" SPDX-License-Identifier: BSD-4-Clause-UC
  10 .\"
  11 .\"     @(#)strtod.3    5.3 (Berkeley) 6/29/91
  12 .\"
  13 .\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu)
  14 .\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt
  15 .\"   (michael@cantor.informatik.rwth-aachen.de)
  16 .\" Added strof, strtold, aeb, 2001-06-07
  17 .\"
  18 .TH strtod 3 (date) "Linux man-pages (unreleased)"
  19 .SH NAME
  20 strtod, strtof, strtold \- convert ASCII string to floating-point number
  21 .SH LIBRARY
  22 Standard C library
  23 .RI ( libc ", " \-lc )
  24 .SH SYNOPSIS
  25 .nf
  26 .B #include <stdlib.h>
  27 .PP
  28 .BI "double strtod(const char *restrict " nptr ", char **restrict " endptr );
  29 .BI "float strtof(const char *restrict " nptr ", char **restrict " endptr );
  30 .BI "long double strtold(const char *restrict " nptr \
  31 ", char **restrict " endptr );
  32 .fi
  33 .PP
  34 .RS -4
  35 Feature Test Macro Requirements for glibc (see
  36 .BR feature_test_macros (7)):
  37 .RE
  38 .PP
  39 .BR strtof (),
  40 .BR strtold ():
  41 .nf
  42     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  43 .fi
  44 .SH DESCRIPTION
  45 The
  46 .BR strtod (),
  47 .BR strtof (),
  48 and
  49 .BR strtold ()
  50 functions convert the initial portion of the string pointed to by
  51 .I nptr
  52 to
  53 .IR double ,
  54 .IR float ,
  55 and
  56 .I long double
  57 representation, respectively.
  58 .PP
  59 The expected form of the (initial portion of the) string is
  60 optional leading white space as recognized by
  61 .BR isspace (3),
  62 an optional plus (\[aq]+\[aq]) or minus sign (\[aq]\-\[aq]) and then either
  63 (i) a decimal number, or (ii) a hexadecimal number,
  64 or (iii) an infinity, or (iv) a NAN (not-a-number).
  65 .PP
  66 A
  67 .I "decimal number"
  68 consists of a nonempty sequence of decimal digits
  69 possibly containing a radix character (decimal point, locale-dependent,
  70 usually \[aq].\[aq]), optionally followed by a decimal exponent.
  71 A decimal exponent consists of an \[aq]E\[aq] or \[aq]e\[aq], followed by an
  72 optional plus or minus sign, followed by a nonempty sequence of
  73 decimal digits, and indicates multiplication by a power of 10.
  74 .PP
  75 A
  76 .I "hexadecimal number"
  77 consists of a "0x" or "0X" followed by a nonempty sequence of
  78 hexadecimal digits possibly containing a radix character,
  79 optionally followed by a binary exponent.
  80 A binary exponent
  81 consists of a \[aq]P\[aq] or \[aq]p\[aq], followed by an optional
  82 plus or minus sign, followed by a nonempty sequence of
  83 decimal digits, and indicates multiplication by a power of 2.
  84 At least one of radix character and binary exponent must be present.
  85 .PP
  86 An
  87 .I infinity
  88 is either "INF" or "INFINITY", disregarding case.
  89 .PP
  90 A
  91 .I NAN
  92 is "NAN" (disregarding case) optionally followed by a string,
  93 .IR (n-char-sequence) ,
  94 where
  95 .I n-char-sequence
  96 specifies in an implementation-dependent
  97 way the type of NAN (see NOTES).
  98 .SH RETURN VALUE
  99 These functions return the converted value, if any.
 100 .PP
 101 If
 102 .I endptr
 103 is not NULL,
 104 a pointer to the character after the last character used in the conversion
 105 is stored in the location referenced by
 106 .IR endptr .
 107 .PP
 108 If no conversion is performed, zero is returned and (unless
 109 .I endptr
 110 is null) the value of
 111 .I nptr
 112 is stored in the location referenced by
 113 .IR endptr .
 114 .PP
 115 If the correct value would cause overflow, plus or minus
 116 .BR HUGE_VAL ,
 117 .BR HUGE_VALF ,
 118 or
 119 .B HUGE_VALL
 120 is returned (according to the return type and sign of the value),
 121 and
 122 .B ERANGE
 123 is stored in
 124 .IR errno .
 125 .PP
 126 If the correct value would cause underflow,
 127 a value with magnitude no larger than
 128 .BR DBL_MIN ,
 129 .BR FLT_MIN ,
 130 or
 131 .B LDBL_MIN
 132 is returned and
 133 .B ERANGE
 134 is stored in
 135 .IR errno .
 136 .SH ERRORS
 137 .TP
 138 .B ERANGE
 139 Overflow or underflow occurred.
 140 .SH ATTRIBUTES
 141 For an explanation of the terms used in this section, see
 142 .BR attributes (7).
 143 .TS
 144 allbox;
 145 lbx lb lb
 146 l l l.
 147 Interface       Attribute       Value
 148 T{
 149 .na
 150 .nh
 151 .BR strtod (),
 152 .BR strtof (),
 153 .BR strtold ()
 154 T}      Thread safety   MT-Safe locale
 155 .TE
 156 .sp 1
 157 .SH VERSIONS
 158 In the glibc implementation, the
 159 .I n-char-sequence
 160 that optionally follows "NAN"
 161 is interpreted as an integer number
 162 (with an optional '0' or '0x' prefix to select base 8 or 16)
 163 that is to be placed in the
 164 mantissa component of the returned value.
 165 .\" From glibc 2.8's stdlib/strtod_l.c:
 166 .\"     We expect it to be a number which is put in the
 167 .\"     mantissa of the number.
 168 .\" It looks as though at least FreeBSD (according to the manual) does
 169 .\" something similar.
 170 .\" C11 says: "An implementation may use the n-char sequence to determine
 171 .\"     extra information to be represented in the NaN's significant."
 172 .SH STANDARDS
 173 C11, POSIX.1-2008.
 174 .SH HISTORY
 175 .TP
 176 .BR strtod ()
 177 C89, POSIX.1-2001.
 178 .TP
 179 .BR strtof ()
 180 .TQ
 181 .BR strtold ()
 182 C99, POSIX.1-2001.
 183 .SH NOTES
 184 Since
 185 0 can legitimately be returned
 186 on both success and failure, the calling program should set
 187 .I errno
 188 to 0 before the call,
 189 and then determine if an error occurred by checking whether
 190 .I errno
 191 has a nonzero value after the call.
 192 .SH EXAMPLES
 193 See the example on the
 194 .BR strtol (3)
 195 manual page;
 196 the use of the functions described in this manual page is similar.
 197 .SH SEE ALSO
 198 .BR atof (3),
 199 .BR atoi (3),
 200 .BR atol (3),
 201 .BR nan (3),
 202 .BR nanf (3),
 203 .BR nanl (3),
 204 .BR strfromd (3),
 205 .BR strtol (3),
 206 .BR strtoul (3)