---
name: "strtonumx"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/strtonum"
---

# strtonumx(3)

reliably convert string value to an integer

Part of [strtonum(3)](/strtonum/3.md).

## NAME

**strtonum**, **strtonumx** – reliably convert string value to an integer

## 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(3)](/atoi/3.md) and [strtol(3)](/strtol/3.md) family of interfaces.

The string may begin with an arbitrary amount of whitespace (as determined by [isspace(3)](/isspace/3.md)) 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(3)](/strtoll/3.md). 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**() and **strtonumx**() functions return 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

Using **strtonum**() and **strtonumx**() 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

- \[ERANGE\]

  The given string was out of range.

- \[EINVAL\]

  The given string did not consist solely of digit characters (for **strtonum**()), or characters which are valid in the given base (for **strtonumx**()).

- \[EINVAL\]

  The supplied *minval* was larger than *maxval*.

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.

## SEE ALSO

[atof(3)](/atof/3.md), [atoi(3)](/atoi/3.md), [atol(3)](/atol/3.md), [atoll(3)](/atoll/3.md), [sscanf(3)](/sscanf/3.md), [strtod(3)](/strtod/3.md), [strtol(3)](/strtol/3.md), [strtoul(3)](/strtoul/3.md)

## STANDARDS

The **strtonum**() function is a BSD extension. The existing alternatives, such as [atoi(3)](/atoi/3.md) and [strtol(3)](/strtol/3.md), are either impossible or difficult to use safely.

## HISTORY

The **strtonum**() function first appeared in OpenBSD 3.6. The **strtonumx**() function first appeared in illumos in 2023.