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