1STRTOD(3P)                 POSIX Programmer's Manual                STRTOD(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       strtod, strtof, strtold — convert a string to a double-precision number
13

SYNOPSIS

15       #include <stdlib.h>
16
17       double strtod(const char *restrict nptr, char **restrict endptr);
18       float strtof(const char *restrict nptr, char **restrict endptr);
19       long double strtold(const char *restrict nptr, char **restrict endptr);
20

DESCRIPTION

22       The functionality described on this reference page is aligned with  the
23       ISO C  standard.  Any  conflict between the requirements described here
24       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2017
25       defers to the ISO C standard.
26
27       These functions shall convert the initial portion of the string pointed
28       to by nptr to double, float, and long  double  representation,  respec‐
29       tively. First, they decompose the input string into three parts:
30
31        1. An  initial, possibly empty, sequence of white-space characters (as
32           specified by isspace())
33
34        2. A subject sequence interpreted as a floating-point constant or rep‐
35           resenting infinity or NaN
36
37        3. A  final  string  of one or more unrecognized characters, including
38           the terminating NUL character of the input string
39
40       Then they shall attempt to convert the subject sequence to a  floating-
41       point number, and return the result.
42
43       The  expected  form  of  the subject sequence is an optional '+' or '-'
44       sign, then one of the following:
45
46        *  A non-empty sequence of  decimal  digits  optionally  containing  a
47           radix  character;  then an optional exponent part consisting of the
48           character 'e' or the character 'E', optionally followed by a '+' or
49           '-' character, and then followed by one or more decimal digits
50
51        *  A 0x or 0X, then a non-empty sequence of hexadecimal digits option‐
52           ally containing a radix character; then an optional binary exponent
53           part  consisting of the character 'p' or the character 'P', option‐
54           ally followed by a '+' or '-' character, and then followed  by  one
55           or more decimal digits
56
57        *  One of INF or INFINITY, ignoring case
58
59        *  One  of  NAN  or  NAN(n-char-sequenceopt), ignoring case in the NAN
60           part, where:
61
62
63               n-char-sequence:
64                   digit
65                   nondigit
66                   n-char-sequence digit
67                   n-char-sequence nondigit
68
69       The subject sequence is defined as the longest initial  subsequence  of
70       the  input  string,  starting with the first non-white-space character,
71       that is of the expected form. The subject sequence contains no  charac‐
72       ters if the input string is not of the expected form.
73
74       If the subject sequence has the expected form for a floating-point num‐
75       ber, the sequence of characters starting with the first  digit  or  the
76       decimal-point  character  (whichever occurs first) shall be interpreted
77       as a floating constant of the C language, except that the radix charac‐
78       ter shall be used in place of a period, and that if neither an exponent
79       part nor a radix character appears in a decimal floating-point  number,
80       or if a binary exponent part does not appear in a hexadecimal floating-
81       point number, an exponent part of the appropriate type with value  zero
82       is  assumed  to  follow  the  last  digit in the string. If the subject
83       sequence begins with a <hyphen-minus>, the  sequence  shall  be  inter‐
84       preted as negated. A character sequence INF or INFINITY shall be inter‐
85       preted as an infinity, if representable in the return type, else as  if
86       it  were  a  floating  constant  that is too large for the range of the
87       return type. A character sequence NAN or NAN(n-char-sequenceopt)  shall
88       be interpreted as a quiet NaN, if supported in the return type, else as
89       if it were a subject sequence part that  does  not  have  the  expected
90       form;  the meaning of the n-char sequences is implementation-defined. A
91       pointer to the final string is stored  in  the  object  pointed  to  by
92       endptr, provided that endptr is not a null pointer.
93
94       If  the  subject  sequence  has the hexadecimal form and FLT_RADIX is a
95       power of 2, the  value  resulting  from  the  conversion  is  correctly
96       rounded.
97
98       The  radix  character  is  defined  in  the  current  locale  (category
99       LC_NUMERIC).  In the POSIX locale, or in a locale where the radix char‐
100       acter  is  not defined, the radix character shall default to a <period>
101       ('.').
102
103       In other than the C or POSIX locale, additional locale-specific subject
104       sequence forms may be accepted.
105
106       If the subject sequence is empty or does not have the expected form, no
107       conversion shall be performed; the value  of  nptr  is  stored  in  the
108       object  pointed  to  by  endptr,  provided  that  endptr  is not a null
109       pointer.
110
111       These functions shall not change the setting of errno if successful.
112
113       Since 0 is returned on error and is also a valid return on success,  an
114       application  wishing  to check for error situations should set errno to
115       0, then call strtod(), strtof(), or strtold(), then check errno.
116

RETURN VALUE

118       Upon successful completion, these functions shall return the  converted
119       value.  If  no  conversion could be performed, 0 shall be returned, and
120       errno may be set to [EINVAL].
121
122       If the correct value is outside  the  range  of  representable  values,
123       ±HUGE_VAL,  ±HUGE_VALF,  or  ±HUGE_VALL shall be returned (according to
124       the sign of the value), and errno shall be set to [ERANGE].
125
126       If the correct value would cause an underflow, a value whose  magnitude
127       is  no  greater  than  the  smallest  normalized positive number in the
128       return type shall be returned and errno set to [ERANGE].
129

ERRORS

131       These functions shall fail if:
132
133       ERANGE The value to be returned would cause overflow or underflow.
134
135       These functions may fail if:
136
137       EINVAL No conversion could be performed.
138
139       The following sections are informative.
140

EXAMPLES

142       None.
143

APPLICATION USAGE

145       If the subject sequence has the hexadecimal form and FLT_RADIX is not a
146       power  of  2,  and  the result is not exactly representable, the result
147       should be one of the two numbers in  the  appropriate  internal  format
148       that  are  adjacent  to the hexadecimal floating source value, with the
149       extra stipulation that the error should have a  correct  sign  for  the
150       current rounding direction.
151
152       If  the  subject  sequence has the decimal form and at most DECIMAL_DIG
153       (defined in <float.h>) significant digits, the result  should  be  cor‐
154       rectly rounded. If the subject sequence D has the decimal form and more
155       than DECIMAL_DIG significant digits, consider the two  bounding,  adja‐
156       cent  decimal strings L and U, both having DECIMAL_DIG significant dig‐
157       its, such that the values of L, D, and U satisfy L  <=  D  <=  U.   The
158       result  should  be  one of the (equal or adjacent) values that would be
159       obtained by correctly rounding L and U according to the current  round‐
160       ing  direction,  with the extra stipulation that the error with respect
161       to D should have a correct sign for the current rounding direction.
162
163       The changes to strtod() introduced by  the  ISO/IEC 9899:1999  standard
164       can  alter  the behavior of well-formed applications complying with the
165       ISO/IEC 9899:1990 standard and thus earlier versions of this  standard.
166       One such example would be:
167
168
169           int
170           what_kind_of_number (char *s)
171           {
172               char *endp;
173               double d;
174               long l;
175
176               d = strtod(s, &endp);
177               if (s != endp && *endp == `\0')
178                   printf("It's a float with value %g\n", d);
179               else
180               {
181                   l = strtol(s, &endp, 0);
182                   if (s != endp && *endp == `\0')
183                       printf("It's an integer with value %ld\n", 1);
184                   else
185                       return 1;
186               }
187               return 0;
188           }
189
190       If the function is called with:
191
192
193           what_kind_of_number ("0x10")
194
195       an  ISO/IEC 9899:1990  standard-compliant  library  will  result in the
196       function printing:
197
198
199           It's an integer with value 16
200
201       With the ISO/IEC 9899:1999 standard, the result is:
202
203
204           It's a float with value 16
205
206       The change in behavior is due to the inclusion of  floating-point  num‐
207       bers  in  hexadecimal  notation without requiring that either a decimal
208       point or the binary exponent be present.
209

RATIONALE

211       None.
212

FUTURE DIRECTIONS

214       None.
215

SEE ALSO

217       fscanf(), isspace(), localeconv(), setlocale(), strtol()
218
219       The  Base  Definitions  volume  of  POSIX.1‐2017,  Chapter  7,  Locale,
220       <float.h>, <stdlib.h>
221
223       Portions  of  this text are reprinted and reproduced in electronic form
224       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
225       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
226       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
227       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
228       event of any discrepancy between this version and the original IEEE and
229       The  Open Group Standard, the original IEEE and The Open Group Standard
230       is the referee document. The original Standard can be  obtained  online
231       at http://www.opengroup.org/unix/online.html .
232
233       Any  typographical  or  formatting  errors that appear in this page are
234       most likely to have been introduced during the conversion of the source
235       files  to  man page format. To report such errors, see https://www.ker
236       nel.org/doc/man-pages/reporting_bugs.html .
237
238
239
240IEEE/The Open Group                  2017                           STRTOD(3P)
Impressum