strtoi(3bsd) 3bsd strtoi(3bsd)

# [NAME](#NAME)

`strtoi` — convert a string value to an intmax\_t integer

# [LIBRARY](#LIBRARY)

library “libbsd”

# [SYNOPSIS](#SYNOPSIS)

`#include <inttypes.h>` (See [libbsd(7)](/man/os/libbsd/libbsd.7) for include usage.)  
`intmax_t`  
`strtoi`(`const char * restrict nptr`, `char ** restrict endptr`, `int base`, `intmax_t lo`, `intmax_t hi`, `int *rstatus`);

# [DESCRIPTION](#DESCRIPTION)

The [`strtoi`](#strtoi)() function converts the string in `nptr` to an `intmax_t` value. The `strtoi`() function uses internally [strtoimax(3)](/man/os/libbsd/strtoimax.3) and ensures that the result is always in the range \[ `lo ..` `hi` ]. In addition it always places `0` on success or a conversion status in the `rstatus` argument, avoiding the `errno` gymnastics the other functions require. The `rstatus` argument can be `NULL` if conversion status is to be ignored.

The string may begin with an arbitrary amount of white space (as determined by [isspace(3)](/man/os/libbsd/isspace.3)) followed by a single optional ‘`+`’ or ‘`-`’ sign. If `base` is zero or 16, the string may then include a ‘`0x`’ or ‘`0X`’ prefix, and the number will be read in base 16; otherwise, a zero `base` is taken as 10 (decimal) unless the next character is ‘`0`’, in which case it is taken as 8 (octal).

The remainder of the string is converted to an [*intmax\_t*](#intmax_t) value in the obvious manner, stopping at the end of the string or at the first character which is not a valid digit in the given base. (In bases above 10, the letter ‘`A`’ in either upper or lower case represents 10, ‘`B`’ represents 11, and so forth, with ‘`Z`’ representing 35.)

If `endptr` is non-nil, [`strtoi`](#strtoi~2)() stores the address of the first invalid character in `*endptr`. If there were no digits at all, however, `strtoi`() stores the original value of `nptr` in `*endptr`. (Thus, if `*nptr` is not ‘`\0`’ but `**endptr` is ‘`\0`’ on return, the entire string was valid.)

# [RETURN VALUES](#RETURN_VALUES)

The `strtoi`() function always returns the closest value in the range specified by the `lo` and `hi` arguments.

The `errno` value is guaranteed to be left unchanged.

Errors are stored as the conversion status in the `rstatus` argument.

# [EXAMPLES](#EXAMPLES)

The following example will always return a number in `[1..99]` range no matter what the input is, and warn if the conversion failed.

```
int e;
intmax_t lval = strtoi(buf, NULL, 0, 1, 99, &e);
if (e)
	warnc(e, "conversion of `%s' to a number failed, using %jd",
	    buf, lval);
```

# [ERRORS](#ERRORS)

\[[`ECANCELED`](#ECANCELED)]

The string did not contain any characters that were converted.

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

The `base` is not between 2 and 36 and does not contain the special value 0.

\[[`ENOTSUP`](#ENOTSUP)]

The string contained non-numeric characters that did not get converted. In this case, `endptr` points to the first unconverted character.

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

The given string was out of range; the value converted has been clamped; or the range given was invalid, i.e. `lo` &gt; `hi`.

The range check is more important than the unconverted characters check, and it is performed first. If a program needs to know if there were unconverted characters when an out of range number has been provided, it needs to supply and test `endptr.`

# [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), [strtod(3)](/man/os/libbsd/strtod.3), [strtoimax(3)](/man/os/libbsd/strtoimax.3), [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), [strtoumax(3)](/man/os/libbsd/strtoumax.3)

# [STANDARDS](#STANDARDS)

The `strtoi`() function is a NetBSD extension.

# [HISTORY](#HISTORY)

The `strtoi`() function first appeared in NetBSD 7.0. OpenBSD introduced the [strtonum(3bsd)](/man/os/libbsd/strtonum.3bsd) function for the same purpose, but the interface makes it impossible to properly differentiate illegal returns.

# [BUGS](#BUGS)

Ignores the current locale.

January 20, 2024 Linux 4.19.0-gvisor

---

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