STRTONUM(3C) | Standard C Library Functions | STRTONUM(3C) |
strtonum
,
strtonumx
— reliably convert
string value to an integer
Standard C Library (libc, -lc)
#include
<stdlib.h>
long long
strtonum
(const char *nptr,
long long minval, long long
maxval, const char **errstr);
long long
strtonumx
(const char *nptr,
long long minval, long long
maxval, const char **errstr, int
base);
The
strtonum
()
and strtonumx
() functions convert the string in
nptr to a long long
value.
These functions were designed to facilitate safe, robust programming and
overcome the shortcomings of the
atoi(3C) and
strtol(3C) family of interfaces.
The string may begin with an arbitrary amount of whitespace (as
determined by isspace(3C)) followed
by a single optional ‘+
’ or
‘-
’ sign.
The remainder of the string is converted to a
long long
value according to base 10 (for
strtonum
())
or the provided base (for strtonumx
()).
The value obtained is then checked against the
provided minval and maxval
bounds. If errstr is non-null,
strtonum
()
and strtonumx
() store an error string in
errstr indicating the failure.
For
strtonumx
()
the value of base is interpreted in the same way as
described in strtoll(3C). In
particular, if the value of base is 0, then the
expected form of nptr is that of a decimal constant,
octal constant or hexadecimal constant, any of which may be preceded by a +
or - sign.
The strtonum
() function returns the result
of the conversion, unless the value would exceed the provided bounds or is
invalid. On error, 0 is returned, errno is set, and
errstr will point to an error message.
errstr will be set to NULL
on
success; this fact can be used to differentiate a successful return of 0
from an error.
Using strtonum
() correctly is meant to be
simpler than the alternative functions.
int iterations; const char *errstr; iterations = strtonum(optarg, 1, 64, &errstr); if (errstr != NULL) errx(1, "number of iterations is %s: %s", errstr, optarg);
The above example will guarantee that the value of iterations is between 1 and 64 (inclusive).
The strtonum
() and
strtonumx
() functions will fail if:
ERANGE
EINVAL
The strtonum
() function will fail if:
EINVAL
The strtonumx
() function will fail if:
EINVAL
If an error occurs, errstr will be set to one of the following strings:
strtonum
()).Safe.
atof(3C), atoi(3C), atol(3C), atoll(3C), sscanf(3C), strtod(3C), strtol(3C), strtoll(3C), strtoul(3C)
strtonum
() is an
OpenBSD extension. The existing alternatives, such
as atoi(3C) and
strtol(3C), are either impossible or
difficult to use safely.
strtonumx
() is an illumos extension.
August 19, 2023 | OmniOS |