1 STRTOD(3C) Standard C Library Functions STRTOD(3C)
2
3
4
5 NAME
6 strtod, strtof, strtold, atof - convert string to floating-point number
7
8 SYNOPSIS
9 #include <stdlib.h>
10
11 double strtod(const char *restrict nptr, char **restrict endptr);
12
13
14 float strtof(const char *restrict nptr, char **restrict endptr);
15
16
17 long double strtold(const char *restrict nptr, char **restrict endptr);
18
19
20 double atof(const char *str);
21
22
23 DESCRIPTION
24 The strtod(), strtof(), and strtold() functions convert the initial
25 portion of the string pointed to by nptr to double, float, and long
26 double representation, respectively. First they decompose the input
27 string into three parts:
28
29 1. An initial, possibly empty, sequence of white-space
30 characters (as specified by isspace(3C))
31
32 2. A subject sequence interpreted as a floating-point constant
33 or representing infinity or NaN
34
35 3. A final string of one or more unrecognized characters,
36 including the terminating null byte of the input string.
37
38
39 Then they attempt to convert the subject sequence to a floating-point
40 number, and return the result.
41
42
43 The expected form of the subject sequence is an optional plus or minus
44 sign, then one of the following:
45
46 o A non-empty sequence of digits optionally containing a radix
47 character, then an optional exponent part
48
49 o A 0x or 0X, then a non-empty sequence of hexadecimal digits
50 optionally containing a radix character, then an optional
51 binary exponent part
52
53 o One of INF or INFINITY, ignoring case
54
55 o One of NAN or NAN(n-char-sequence(opt)), ignoring case in
56 the NAN part, where:
57
58 n-char-sequence:
59 digit
60 nondigit
61 n-char-sequence digit
62 n-char-sequence nondigit
63
64
65
66 In default mode for strtod(), only decimal, INF/INFINITY, and
67 NAN/NAN(n-char-sequence) forms are recognized. In C99/SUSv3 mode,
68 hexadecimal strings are also recognized.
69
70
71 In default mode for strtod(), the n-char-sequence in the NAN(n-char-
72 sequence) form can contain any character except ')' (right parenthesis)
73 or '\0' (null). In C99/SUSv3 mode, the n-char-sequence can contain
74 only upper and lower case letters, digits, and '_' (underscore).
75
76
77 The strtof() and strtold() functions always function in
78 C99/SUSv3-conformant mode.
79
80
81 The subject sequence is defined as the longest initial subsequence of
82 the input string, starting with the first non-white-space character,
83 that is of the expected form. The subject sequence contains no
84 characters if the input string is not of the expected form.
85
86
87 If the subject sequence has the expected form for a floating-point
88 number, the sequence of characters starting with the first digit or the
89 decimal-point character (whichever occurs first) is interpreted as a
90 floating constant of the C language, except that the radix character is
91 used in place of a period, and that if neither an exponent part nor a
92 radix character appears in a decimal floating-point number, or if a
93 binary exponent part does not appear in a hexadecimal floating-point
94 number, an exponent part of the appropriate type with value zero is
95 assumed to follow the last digit in the string. If the subject sequence
96 begins with a minus sign, the sequence is interpreted as negated. A
97 character sequence INF or INFINITY is interpreted as an infinity. A
98 character sequence NAN or NAN(n-char-sequence(opt)) is interpreted as a
99 quiet NaN. A pointer to the final string is stored in the object
100 pointed to by endptr, provided that endptr is not a null pointer.
101
102
103 If the subject sequence has either the decimal or hexadecimal form, the
104 value resulting from the conversion is rounded correctly according to
105 the prevailing floating point rounding direction mode. The conversion
106 also raises floating point inexact, underflow, or overflow exceptions
107 as appropriate.
108
109
110 The radix character is defined in the program's locale (category
111 LC_NUMERIC). In the POSIX locale, or in a locale where the radix
112 character is not defined, the radix character defaults to a period
113 ('.').
114
115
116 If the subject sequence is empty or does not have the expected form, no
117 conversion is performed; the value of nptr is stored in the object
118 pointed to by endptr, provided that endptr is not a null pointer.
119
120
121 The strtod() function does not change the setting of errno if
122 successful.
123
124
125 The atof(str) function call is equivalent to strtod(nptr, (char
126 **)NULL).
127
128 RETURN VALUES
129 Upon successful completion, these functions return the converted value.
130 If no conversion could be performed, 0 is returned.
131
132
133 If the correct value is outside the range of representable values,
134 +-HUGE_VAL, +-HUGE_VALF, or +-HUGE_VALL is returned (according to the
135 sign of the value), a floating point overflow exception is raised, and
136 errno is set to ERANGE.
137
138
139 If the correct value would cause an underflow, the correctly rounded
140 result (which may be normal, subnormal, or zero) is returned, a
141 floating point underflow exception is raised, and errno is set to
142 ERANGE.
143
144 ERRORS
145 These functions will fail if:
146
147 ERANGE
148 The value to be returned would cause overflow or underflow
149
150
151
152 These functions may fail if:
153
154 EINVAL
155 No conversion could be performed.
156
157
158 USAGE
159 Since 0 is returned on error and is also a valid return on success, an
160 application wishing to check for error situations should set errno to
161 0, then call strtod(), strtof(), or strtold(), then check errno.
162
163
164 The changes to strtod() introduced by the ISO/IEC 9899: 1999 standard
165 can alter the behavior of well-formed applications complying with the
166 ISO/IEC 9899: 1990 standard and thus earlier versions of IEEE Std
167 1003.1-200x. One such example would be:
168
169 int
170 what_kind_of_number (char *s)
171 {
172 char *endp;
173 double d;
174 long l;
175 d = strtod(s, &endp);
176 if (s != endp && *endp == '\0')
177 printf("It's a float with value %g\n", d);
178 else
179 {
180 l = strtol(s, &endp, 0);
181 if (s != endp && *endp == '\0')
182 printf("It's an integer with value %ld\n", 1);
183 else
184 return 1;
185 }
186 return 0;
187 }
188
189
190
191 If the function is called with:
192
193 what_kind_of_number ("0x10")
194
195
196
197 an ISO/IEC 9899: 1990 standard-compliant library will result in the
198 function printing:
199
200 It's an integer with value 16
201
202
203
204 With the ISO/IEC 9899: 1999 standard, the result is:
205
206 It's a float with value 16
207
208
209
210 The change in behavior is due to the inclusion of floating-point
211 numbers in hexadecimal notation without requiring that either a decimal
212 point or the binary exponent be present.
213
214 ATTRIBUTES
215 See attributes(5) for descriptions of the following attributes:
216
217
218
219
220 +--------------------+-------------------------+
221 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
222 +--------------------+-------------------------+
223 |CSI | Enabled |
224 +--------------------+-------------------------+
225 |Interface Stability | Standard |
226 +--------------------+-------------------------+
227 |MT-Level | MT-Safe with exceptions |
228 +--------------------+-------------------------+
229
230 SEE ALSO
231 isspace(3C), localeconv(3C), scanf(3C), setlocale(3C), strtol(3C),
232 attributes(5), standards(5)
233
234 NOTES
235 The strtod() and atof() functions can be used safely in multithreaded
236 applications, as long as setlocale(3C) is not called to change the
237 locale.
238
239
240 The DESCRIPTION and RETURN VALUES sections above are very similar to
241 the wording used by the Single UNIX Specification version 2 (SUSv2) and
242 the 1989 C Standard to describe the behavior of the strtod() function.
243 Since some users have reported that they find the description
244 confusing, the following notes might be helpful.
245
246 1. The strtod() function does not modify the string pointed to
247 by str and does not malloc() space to hold the decomposed
248 portions of the input string.
249
250 2. If endptr is not (char **)NULL, strtod() will set the
251 pointer pointed to by endptr to the first byte of the "final
252 string of unrecognized characters". (If all input
253 characters were processed, the pointer pointed to by endptr
254 will be set to point to the null character at the end of the
255 input string.)
256
257 3. If strtod() returns 0.0, one of the following occurred:
258
259 a. The "subject sequence" was not an empty string, but
260 evaluated to 0.0. (In this case, errno will be left
261 unchanged.)
262
263 b. The "subject sequence" was an empty string . In this
264 case, errno will be left unchanged. (The Single UNIX
265 Specification version 2 allows errno to be set to EINVAL
266 or to be left unchanged. The C Standard does not specify
267 any specific behavior in this case.)
268
269 c. The "subject sequence" specified a numeric value whose
270 conversion resulted in a floating point underflow. In
271 this case, an underflow exception is raised and errno is
272 set to ERANGE.
273 Note that the standards do not require that implementations
274 distinguish between these three cases. An application can
275 determine case (b) by making sure that there are no leading white-
276 space characters in the string pointed to by str and giving
277 strtod() an endptr that is not (char **)NULL. If endptr points to
278 the first character of str when strtod() returns, you have detected
279 case (b). Case (c) can be detected by examining the underflow flag
280 or by looking for a non-zero digit before the exponent part of the
281 "subject sequence". Note, however, that the decimal-point
282 character is locale-dependent.
283
284 4. If strtod() returns +HUGE_VAL or -HUGE_VAL, one of the
285 following occurred:
286
287 a. If +HUGE_VAL is returned and errno is set to ERANGE, a
288 floating point overflow occurred while processing a
289 positive value, causing a floating point overflow
290 exception to be raised.
291
292 b. If -HUGE_VAL is returned and errno is set to ERANGE, a
293 floating point overflow occurred while processing a
294 negative value, causing a floating point overflow
295 exception to be raised.
296
297 c. If strtod() does not set errno to ERANGE, the value
298 specified by the "subject string" converted to +HUGE_VAL
299 or -HUGE_VAL, respectively.
300 Note that if errno is set to ERANGE when strtod() is called, case
301 (c) can be distinguished from cases (a) and (b) by examining either
302 ERANGE or the overflow flag.
303
304
305
306 August 25, 2019 STRTOD(3C)