atof(3C)
NAME
strtod, atof - convert string to double-precision number
SYNOPSIS
#include <stdlib.h>
double strtod(const char *str, char **endptr);
double atof(const char *str);
DESCRIPTION
The strtod() function converts the initial portion of the
string pointed to by str to type double representation.
First it decomposes the input string into three parts: an
initial, possibly empty, sequence of white-space characters
(as specified by isspace(3C)); a subject sequence inter-
preted as a floating-point constant; and a final string of
one or more unrecognized characters, including the terminat-
ing null byte of the input string. Then it attempts to con-
vert the subject sequence to a floating-point number, and
returns the result.
The expected form of the subject sequence is an optional +
or - sign, then a non-empty sequence of digits optionally
containing a radix character, then an optional exponent
part. An exponent part consists of e or E, followed by an
optional sign, followed by one or more decimal digits. The
subject sequence is defined as the longest initial subse-
quence of the input string, starting with the first non-
white-space character, that is of the expected form. The
subject sequence is empty if the input string is empty or
consists entirely of white-space characters, or if the first
character that is not white space is other than a sign, a
digit or a radix character.
If the subject sequence has the expected form, the sequence
starting with the first digit or the radix character (which-
ever occurs first) is interpreted as a floating constant of
the C language, except that the radix character is used in
place of a period, and that if neither an exponent part nor
a radix character appears, a radix character is assumed to
follow the last digit in the string. If the subject sequence
begins with a minus sign, the value resulting from the
conversion is negated. A pointer to the final string is
stored in the object pointed to by endptr, provided that
endptr is not a null pointer.
The radix character is defined in the program's locale
(category LC_NUMERIC). In the POSIX locale, or in a locale
where the radix character is not defined, the radix charac-
ter defaults to a period (.).
In other than the POSIX locale, other implementation-
dependent subject sequence forms may be accepted.
If the subject sequence is empty or does not have the
expected form, no conversion is performed; the value of str
is stored in the object pointed to by endptr, provided that
endptr is not a null pointer.
atof()
The atof(str) function call is equivalent to strtod(str,
(char **)NULL).
RETURN VALUES
Upon successful completion, strtod() returns the converted
value. If no conversion could be performed, 0 is returned
and errno may be set to EINVAL.
If the correct value is outside the range of representable
values, _HUGE is returned (according to the sign of the
value), and errno is set to ERANGE. When the -Xc or -Xa com-
pilation options are used, HUGE_VAL is returned instead of
HUGE.
If the correct value would cause an underflow, 0 is returned
and errno is set to ERANGE.
If str is NaN, then atof() returns NaN.
ERRORS
The strtod() function will fail if:
ERANGE
The value to be returned would cause overflow or
underflow. The strtod() function may fail if:
EINVAL
No conversion could be performed.
USAGE
Because 0 is returned on error and is also a valid return on
success, an application wishing to check for error situa-
tions should set errno to 0, then call strtod(), then check
errno and if it is non-zero, assume an error has occurred.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe with exceptions |
|_____________________________|_____________________________|
| CSI | Enabled |
|_____________________________|_____________________________|
SEE ALSO
isspace(3C), localeconv(3C), scanf(3C), setlocale(3C),
strtol(3C), attributes(5), standards(5)
NOTES
The strtod() and atof() functions can be used safely in mul-
tithreaded applications, as long as setlocale(3C) is not
called to change the locale.
The DESCRIPTION and RETURN VALUES sections above are very
similar to the wording used by the Single UNIX Specification
version 2 and the 1989 C Standard to describe the behavior
of the strtod() function. Since some users have reported
that they find the description confusing, the following
notes may be helpful.
1. The strtod() function does not modify the string pointed
to by str and does not malloc() space to hold the decom-
posed portions of the input string.
2. If endptr is not (char **)NULL, strtod() will set the
pointer pointed to by endptr to the first byte of the
"final string of unrecognized characters". (If all input
characters were processed, the pointer pointed to by
endptr will be set to point to the null character at the
end of the input string.)
3. If strtod() returns 0.0, one of the following occurred:
a. The "subject sequence" was not an empty string, but
evaluated to 0.0. (In this case, errno will be left
unchanged.)
b. The "subject sequence" was an empty string. (In this
case, the Single UNIX Specification version 2 allows
errno to be set to EINVAL or to be left unchanged.
The C Standard does not specify any specific behavior
in this case.)
c. The "subject sequence" specified a numeric value that
would cause a floating point underflow. (In this
case, errno may be set to ERANGE or may be left
unchanged.)
Note that the standards do not require that implementations
distinguish between these three cases. An application can
determine case (b) by making sure that there are no leading
white-space characters in the string pointed to by str and
giving strtod() an endptr that is not (char **)NULL. If
endptr points to the first chartacter of str when strtod()
returns, you have detected case (b). Case (c) can be
detected by looking for a non-zero digit before the exponent
part of the "subject sequence". Note, however, that the
decimal-point character is locale-dependent.
4. If strtod() returns +HUGE_VAL or -HUGE_VAL, one of the
following occurred:
a. If +HUGE_VAL is returned and errno is set to ERANGE, a
floating point overflow occurred while processing a
positive value.
b. If -HUGE_VAL is returned and errno is set to ERANGE, a
floating point overflow occurred while processing a
negative value.
c. If strtod() does not set errno to ERANGE, the value
specified by the "subject string" converted to
+HUGE_VAL or -HUGE_VAL, respectively.
Note that if errno is set to ERANGE when strtod() is called,
case (c) is indistinguishable from cases (a) and (b).
Man(1) output converted with
man2html