1strtod(3C)               Standard C Library Functions               strtod(3C)
2
3
4

NAME

6       strtod, strtof, strtold, atof - convert string to floating-point number
7

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

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  charac‐
30                  ters (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, hexa‐
68       decimal strings are also recognized.
69
70
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)
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  C99/SUSv3-con‐
78       formant 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 charac‐
84       ters 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 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
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  char‐
112       acter is not defined, the radix character defaults to a period ('.').
113
114
115       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
119
120       The  strtod() function does not change the setting of errno if success‐
121       ful.
122
123
124       The  atof(str)  function  call  is  equivalent  to  strtod(nptr,  (char
125       **)NULL).
126

RETURN VALUES

128       Upon successful completion, these functions return the converted value.
129       If no conversion could be performed, 0 is returned.
130
131
132       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
137
138       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

ERRORS

143       These functions will fail if:
144
145       ERANGE    The value to be returned would cause overflow or underflow
146
147
148
149       These functions may fail if:
150
151       EINVAL    No conversion could be performed.
152
153

USAGE

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
159
160       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
165         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
185
186
187       If the function is called with:
188
189         what_kind_of_number ("0x10")
190
191
192
193       an ISO/IEC 9899: 1990 standard-compliant library  will  result  in  the
194       function printing:
195
196         It's an integer with value 16
197
198
199
200       With the ISO/IEC 9899: 1999 standard, the result is:
201
202         It's a float with value 16
203
204
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

ATTRIBUTES

211       See attributes(5) for descriptions of the following attributes:
212
213
214
215
216       ┌─────────────────────────────┬─────────────────────────────┐
217       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
218       ├─────────────────────────────┼─────────────────────────────┤
219       │CSI                          │Enabled                      │
220       ├─────────────────────────────┼─────────────────────────────┤
221       │Interface Stability          │Standard                     │
222       ├─────────────────────────────┼─────────────────────────────┤
223       │MT-Level                     │MT-Safe with exceptions      │
224       └─────────────────────────────┴─────────────────────────────┘
225

SEE ALSO

227       isspace(3C),   localeconv(3C),  scanf(3C),  setlocale(3C),  strtol(3C),
228       attributes(5), standards(5)
229

NOTES

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
235
236       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
242           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
246           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
253           3.     If strtod() returns 0.0, one of the following occurred:
254
255               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
259               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
265               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
280           4.     If  strtod() returns +HUGE_VAL or −HUGE_VAL, one of the fol‐
281                  lowing occurred:
282
283               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
288               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
293               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.
299
300
301
302SunOS 5.11                        1 Nov 2003                        strtod(3C)
Impressum