---
name: "strtonum"
section: "3bsd"
platform: "linux"
package: "libbsd"
version: "0.12.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/strtonum/3bsd"
---

# strtonum(3bsd)

reliably convert string value to an integer

## NAME

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

## LIBRARY

library “libbsd”

## SYNOPSIS

**#include \<limits.h\>**

**#include \<stdlib.h\>**

(See [libbsd(7)](/libbsd/7.md) for include usage.)

*long* *long*\

**strtonum**(*const char \*nptr*, *long long minval*, *long long maxval*, *const char \*\*errstr*);

## DESCRIPTION

The **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)](/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.

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

## 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

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

- \[EINVAL\]

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

- \[ERANGE\]

  The given string was out of range.

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 digit characters.

## 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), [strtoi(3bsd)](/strtoi/3bsd.md), [strtol(3)](/strtol/3.md), [strtoll(3)](/strtoll/3.md), [strtou(3bsd)](/strtou/3bsd.md), [strtoul(3)](/strtoul/3.md), [strtoull(3)](/strtoull/3.md)

## STANDARDS

**strtonum**() is a BSD extension.

## HISTORY

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

## CAVEATS

The **strtonum**() function was 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, 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)](/strtou/3bsd.md) and [strtoi(3bsd)](/strtoi/3bsd.md).