ATOF(3) BSD ATOF(3)
NAME
atof, atoi, atol, strtod, strtol, strtoul - convert strings to numbers
SYNOPSIS
#include <stdlib.h>
double atof(nptr)
const char *nptr;
int atoi(nptr)
const char *nptr;
long int atol(nptr)
const char *nptr;
double strtod(nptr, endptr)
const char *nptr;
char **endptr;
long int strtol(nptr, endptr, base)
const char *nptr;
char **endptr;
int base;
unsigned long int strtoul(nptr, endptr, base)
const char *nptr;
char **endptr;
int base;
DESCRIPTION
strtod, strtol, and strtoul convert the initial portion of the string
pointed to by nptr to double, long int, and unsigned long int
representation, respectively. These functions first decompose the input
string into three parts: an initial, possibly empty, sequence of white-
space characters (as specified by isspace (ctype(3))), a subject sequence
resembling either a floating-point constant (in the case of strtod), or
an integer or unsigned long integer represented in some radix determined
by the value of base (in the case of strtol and strtoul, respectively),
and a final string of one or more unrecognized characters, including the
terminating null character of the input string. Then they attempt to
convert the subject sequence to a floating-point number, an integer, or
an unsigned integer, respectively, and return the result.
strtod expects a subject sequence consisting of an optional plus or minus
sign, then a nonempty sequence of digits optionally containing a decimal
point character, then an optional exponent part, but no floating suffix.
The subject sequence is defined as the longest initial subsequence of the
input string, starting with the first non-white-space character, that is
of the expected form. The subject sequence contains no characters if the
input string is empty or consists entirely of white space, or if the
first non-white-space characters is other than a sign, a digit, or a
decimal point character.
If the subject sequence has the form strtod expects, the sequence of
characters starting with the first digit or the decimal point character
(whichever occurs first) is interpreted as a floating constant, except
that the decimal point character is used in place of a period, and that
if neither an exponent part nor a decimal point character appears, a
decimal point 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 form of the subject sequence that strtol and strtoul expect depends
upon the value of base. If the value of base is zero, strtol and strtoul
expect a subject sequence consisting of an integer constant, optionally
preceded by a plus or minus sign, but not including an integer suffix.
If the value of base is between 2 and 36, strtol and strtoul expect a
subject sequence consisting of a sequence of letters and digits
representing an integer with the radix specified by base, optionally
preceded by a plus or minus sign, but not including an integer suffix.
The letters from "a" (or "A") through "z" (or "Z") are ascribed the
values 10 to 35; only letters whose ascribed values are less than that of
base are permitted. If the value of base is 16, the characters "0x" or
"0X" may optionally precede the sequence of letters and digits, following
the sign, if present.
The subject sequence, in the case of strtol and strtoul, is defined as
the longest initial subsequence of the input string, starting with the
first non-white-space character, that is of the expected form. The
subject sequence contains no characters if the input string is empty or
consists entirely of white space, or if the first non-white-space
character is other than a sign or a permissible letter or digit.
If the subject sequence has the form strtol and strtoul expect and the
value of base is zero, the sequence of characters starting with the first
digit is interpreted as an integer constant. If the subject sequence
has the form strtol and strtoul expect and the value of base is between 2
and 36, it is used as the base for conversion, ascribing to each letter
its value as given above. 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.
If the subject sequence is empty or does not have the form strtod,
strtol, or strtoul expect, no conversion is done. The value of nptr is
stored in the object pointed to by endptr, provided that endptr is not a
null pointer.
atof converts the initial portion of the string pointed to by nptr to
double representation. Except for the behavior on error, it is
equivalent to
strtod(nptr, (char **)NULL)
If the value cannot be represented, the behavior is undefined.
atoi converts the initial portion of the string pointed to by nptr to int
representation. Except for the behavior on error, it is equivalent to
(int)strtol(nptr, (char **)NULL, 10)
If the value cannot be represented, the behavior is undefined.
atol converts the initial portion of the string pointed to by nptr to
long int representation. Except for the behavior on error, it is
equivalent to
strtol(nptr, (char **)NULL, 10)
SEE ALSO
ctype(3), scanf(3S)
DIAGNOSTICS
These functions return the converted value, if any. If atof, atoi, or
atol result in a value that cannot be represented, their behavior is
undefined. If strtod, strtol, or strtoul could not convert the string
pointed to by nptr, they return zero. If the correct value is outside
the range of representable values, strtod, strtol, and strtoul set errno
to ERANGE. In this case, strtod returns plus or minus HUGE_VAL
(according to the sign of the value), strtol returns LONG_MAX or LONG_MIN
(according to the sign of the value) and strtoul returns ULONG_MAX.
NOTE
Parts of this discussion are adapted from ANS X3.159-1989.
BUGS
atof, atoi, and atol do not provide for overflow.