1strtod(3C) Standard C Library Functions strtod(3C)
2
6 strtod, strtof, strtold, atof - convert string to floating-point number
7
9 #include <stdlib.h>
10 double strtod(const char *restrict nptr, char **restrict endptr);
12 float strtof(const char *restrict nptr, char **restrict endptr);
15 long double strtold(const char *restrict nptr, char **restrict endptr);
18 double atof(const char *str);
21
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 1. An initial, possibly empty, sequence of white-space charac‐
30 ters (as specified by isspace(3C))
31 2. A subject sequence interpreted as a floating-point constant
33 or representing infinity or NaN
34 3. A final string of one or more unrecognized characters,
36 including the terminating null byte of the input string.
37 Then they attempt to convert the subject sequence to a floating-point
40 number, and return the result.
41 The expected form of the subject sequence is an optional plus or minus
44 sign, then one of the following:
45 o A non-empty sequence of digits optionally containing a radix
47 character, then an optional exponent part
48 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 o One of INF or INFINITY, ignoring case
54 o One of NAN or NAN(n-char-sequence(opt)), ignoring case in
56 the NAN part, where:
57 n-char-sequence:
59 digit
60 nondigit
61 n-char-sequence digit
62 n-char-sequence nondigit
63 In default mode for strtod(), only decimal, INF/INFINITY, and
67 NAN/NAN(n-char-sequence) forms are recognized. In C99/SUSv3 mode, hexa‐
68 decimal strings are also recognized.
69 In default mode for strtod(), the n-char-sequence in the NAN(n-char-
72 equence) 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 The strtof() and strtold() functions always function in C99/SUSv3-con‐
78 formant mode.
79 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 charac‐
84 ters if the input string is not of the expected form.
85 If the subject sequence has the expected form for a floating-point num‐
88 ber, 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 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 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 char‐
112 acter is not defined, the radix character defaults to a period ('.').
113 If the subject sequence is empty or does not have the expected form, no
116 conversion is performed; the value of nptr is stored in the object
117 pointed to by endptr, provided that endptr is not a null pointer.
118 The strtod() function does not change the setting of errno if success‐
121 ful.
122 The atof(str) function call is equivalent to strtod(nptr, (char
125 **)NULL).
126
128 Upon successful completion, these functions return the converted value.
129 If no conversion could be performed, 0 is returned.
130 If the correct value is outside the range of representable values,
133 ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned (according to the sign
134 of the value), a floating point overflow exception is raised, and errno
135 is set to ERANGE.
136 If the correct value would cause an underflow, the correctly rounded
139 result (which may be normal, subnormal, or zero) is returned, a float‐
140 ing point underflow exception is raised, and errno is set to ERANGE.
141
143 These functions will fail if:
144 ERANGE The value to be returned would cause overflow or underflow
146 These functions may fail if:
150 EINVAL No conversion could be performed.
152
155 Since 0 is returned on error and is also a valid return on success, an
156 application wishing to check for error situations should set errno to
157 0, then call strtod(), strtof(), or strtold(), then check errno.
158 The changes to strtod() introduced by the ISO/IEC 9899: 1999 standard
161 can alter the behavior of well-formed applications complying with the
162 ISO/IEC 9899: 1990 standard and thus earlier versions of IEEE Std
163 1003.1-200x. One such example would be:
164 int
166 what_kind_of_number (char *s)
167 {
168 char *endp;
169 double d;
170 long l;
171 d = strtod(s, &endp);
172 if (s != endp && *endp == ` ')
173 printf("It's a float with value %g\n", d);
174 else
175 {
176 l = strtol(s, &endp, 0);
177 if (s != endp && *endp == `\0')
178 printf("It's an integer with value %ld\n", 1);
179 else
180 return 1;
181 }
182 return 0;
183 }
184 If the function is called with:
188 what_kind_of_number ("0x10")
190 an ISO/IEC 9899: 1990 standard-compliant library will result in the
194 function printing:
195 It's an integer with value 16
197 With the ISO/IEC 9899: 1999 standard, the result is:
201 It's a float with value 16
203 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
211 See attributes(5) for descriptions of the following attributes:
212 ┌─────────────────────────────┬─────────────────────────────┐
217 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
218 ├─────────────────────────────┼─────────────────────────────┤
219 │CSI │Enabled │
220 ├─────────────────────────────┼─────────────────────────────┤
221 │Interface Stability │Standard │
222 ├─────────────────────────────┼─────────────────────────────┤
223 │MT-Level │MT-Safe with exceptions │
224 └─────────────────────────────┴─────────────────────────────┘
225
227 isspace(3C), localeconv(3C), scanf(3C), setlocale(3C), strtol(3C),
228 attributes(5), standards(5)
229
231 The strtod() and atof() functions can be used safely in multithreaded
232 applications, as long as setlocale(3C) is not called to change the
233 locale.
234 The DESCRIPTION and RETURN VALUES sections above are very similar to
237 the wording used by the Single UNIX Specification version 2 (SUSv2) and
238 the 1989 C Standard to describe the behavior of the strtod() function.
239 Since some users have reported that they find the description confus‐
240 ing, the following notes might be helpful.
241 1. The strtod() function does not modify the string pointed to
243 by str and does not malloc() space to hold the decomposed
244 portions of the input string.
245 2. If endptr is not (char **)NULL, strtod() will set the
247 pointer pointed to by endptr to the first byte of the "final
248 string of unrecognized characters". (If all input charac‐
249 ters were processed, the pointer pointed to by endptr will
250 be set to point to the null character at the end of the
251 input string.)
252 3. If strtod() returns 0.0, one of the following occurred:
254 a. The "subject sequence" was not an empty string, but
256 evaluated to 0.0. (In this case, errno will be left
257 unchanged.)
258 b. The "subject sequence" was an empty string . In this
260 case, errno will be left unchanged. (The Single UNIX
261 Specification version 2 allows errno to be set to EINVAL
262 or to be left unchanged. The C Standard does not specify
263 any specific behavior in this case.)
264 c. The "subject sequence" specified a numeric value whose
266 conversion resulted in a floating point underflow. In
267 this case, an underflow exception is raised and errno is
268 set to ERANGE.
269 Note that the standards do not require that implementations distin‐
270 guish between these three cases. An application can determine case
271 (b) by making sure that there are no leading white-space characters
272 in the string pointed to by str and giving strtod() an endptr that
273 is not (char **)NULL. If endptr points to the first character of
274 str when strtod() returns, you have detected case (b). Case (c)
275 can be detected by examining the underflow flag or by looking for a
276 non-zero digit before the exponent part of the "subject sequence".
277 Note, however, that the decimal-point character is locale-depen‐
278 dent.
279 4. If strtod() returns +HUGE_VAL or −HUGE_VAL, one of the fol‐
281 lowing occurred:
282 a. If +HUGE_VAL is returned and errno is set to ERANGE, a
284 floating point overflow occurred while processing a pos‐
285 itive value, causing a floating point overflow exception
286 to be raised.
287 b. If −HUGE_VAL is returned and errno is set to ERANGE, a
289 floating point overflow occurred while processing a neg‐
290 ative value, causing a floating point overflow exception
291 to be raised.
292 c. If strtod() does not set errno to ERANGE, the value
294 specified by the "subject string" converted to +HUGE_VAL
295 or −HUGE_VAL, respectively.
296 Note that if errno is set to ERANGE when strtod() is called, case
297 (c) can be distinguished from cases (a) and (b) by examining either
298 ERANGE or the overflow flag.
299SunOS 5.11 1 Nov 2003 strtod(3C)