strtonum(3bsd) 3bsd strtonum(3bsd)

# [NAME](#NAME)

`strtonum` — reliably convert string value to an integer

# [LIBRARY](#LIBRARY)

library “libbsd”

# [SYNOPSIS](#SYNOPSIS)

`#include <limits.h>`  
`#include <stdlib.h>` (See [libbsd(7)](/man/os/libbsd/libbsd.7) for include usage.)  
`long long`  
`strtonum`(`const char *nptr`, `long long minval`, `long long maxval`, `const char **errstr`);

# [DESCRIPTION](#DESCRIPTION)

The [`strtonum`](#strtonum)() function converts the string in `nptr` to a `long long` value.

The string may begin with an arbitrary amount of whitespace (as determined by [isspace(3)](/man/os/libbsd/isspace.3)) followed by a single optional ‘`+`’ or ‘`-`’ sign.

The remainder of the string is converted to a `long long` value according to base 10.

The value obtained is then checked against the provided `minval` and `maxval` bounds. If `errstr` is non-null, [`strtonum`](#strtonum~2)() stores an error string in `*errstr` indicating the failure.

# [RETURN VALUES](#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. On success, `*errstr` will be set to `NULL`; this fact can be used to differentiate a successful return of 0 from an error.

# [EXAMPLES](#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)
	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](#ERRORS)

\[[`EINVAL`](#EINVAL)]

The given string did not consist solely of digit characters; or `minval` was larger than `maxval`.

\[[`ERANGE`](#ERANGE)]

The given string was out of range.

If an error occurs, `errstr` will be set to one of the following strings:

[`too large`](#too)

The result was larger than the provided maximum value.

[`too small`](#too~2)

The result was smaller than the provided minimum value.

[`invalid`](#invalid)

The string did not consist solely of digit characters.

# [SEE ALSO](#SEE_ALSO)

[atof(3)](/man/os/libbsd/atof.3), [atoi(3)](/man/os/libbsd/atoi.3), [atol(3)](/man/os/libbsd/atol.3), [atoll(3)](/man/os/libbsd/atoll.3), [sscanf(3)](/man/os/libbsd/sscanf.3), [strtod(3)](/man/os/libbsd/strtod.3), [strtoi(3bsd)](/man/os/libbsd/strtoi.3bsd), [strtol(3)](/man/os/libbsd/strtol.3), [strtoll(3)](/man/os/libbsd/strtoll.3), [strtou(3bsd)](/man/os/libbsd/strtou.3bsd), [strtoul(3)](/man/os/libbsd/strtoul.3), [strtoull(3)](/man/os/libbsd/strtoull.3)

# [STANDARDS](#STANDARDS)

`strtonum`() is a BSD extension.

# [HISTORY](#HISTORY)

The `strtonum`() function first appeared in OpenBSD 3.6. `strtonum`() was redesigned in NetBSD 8.0 as [strtoi(3bsd)](/man/os/libbsd/strtoi.3bsd) and [strtou(3bsd)](/man/os/libbsd/strtou.3bsd).

# [CAVEATS](#CAVEATS)

The `strtonum`() function was designed to facilitate safe, robust programming and overcome the shortcomings of the [atoi(3)](/man/os/libbsd/atoi.3) and [strtol(3)](/man/os/libbsd/strtol.3) family of interfaces, however there are problems with the `strtonum`() API:

- will return 0 on failure; 0 might not be in range, so that necessitates an error check even if you want to avoid it
- does not differentiate 'illegal' returns, so we can't tell the difference between partial and no conversions
- returns english strings
- can't set the base, or find where the conversion ended
- hardcodes long long integer type

To overcome the shortcomings of `strtonum`() NetBSD provides [strtou(3bsd)](/man/os/libbsd/strtou.3bsd) and [strtoi(3bsd)](/man/os/libbsd/strtoi.3bsd).

January 18, 2015 Linux 4.19.0-gvisor

---

Document: strtonum(3bsd) from libbsd 0.12.2-r11 (Chainguard OS)
Source: https://gitlab.freedesktop.org/libbsd/libbsd