STRTONUM(3C) Standard C Library Functions STRTONUM(3C)
NAME
strtonum,
strtonumx - reliably convert string value to an integer
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#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);
DESCRIPTION
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.
RETURN VALUES
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.
EXAMPLES
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).
ERRORS
The
strtonum() and
strtonumx() functions will fail if:
ERANGE The value to be returned falls outside of the
specified range.
EINVAL
minval was larger than
maxval.
The
strtonum() function will fail if:
EINVAL The given string did not consist solely of digit
characters.
The
strtonumx() function will fail if:
EINVAL The specified base was invalid, or the given string
did not consist solely of characters which are valid
in that base.
If an error occurs,
errstr will be set to one of the following strings:
"too large" The result was larger than the provided maximum value.
"too small" The result was smaller than the provided minimum value.
"invalid" The string did not consist solely of characters valid in
the specified base (or base 10 for
strtonum()).
"unparsable; invalid base specified"
The specified base was outside the permitted range.
INTERFACE STABILITY
Committed.
MT-LEVEL Safe.
SEE ALSO
atof(3C),
atoi(3C),
atol(3C),
atoll(3C),
sscanf(3C),
strtod(3C),
strtol(3C),
strtoll(3C),
strtoul(3C)STANDARDS
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.
illumos August 19, 2023 illumos
