1.\" Copyright (c) 2004 Ted Unangst 2.\" Copyright 2023 Oxide Computer Company 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.\" $OpenBSD: strtonum.3,v 1.13 2006/04/25 05:15:42 tedu Exp $ 17.\" 18.Dd January 15, 2026 19.Dt STRTONUM 3 20.Os 21.Sh NAME 22.Nm strtonum , 23.Nm strtonumx 24.Nd "reliably convert string value to an integer" 25.Sh SYNOPSIS 26.In stdlib.h 27.Ft long long 28.Fo strtonum 29.Fa "const char *nptr" 30.Fa "long long minval" 31.Fa "long long maxval" 32.Fa "const char **errstr" 33.Fc 34.Ft long long 35.Fo strtonumx 36.Fa "const char *nptr" 37.Fa "long long minval" 38.Fa "long long maxval" 39.Fa "const char **errstr" 40.Fa "int base" 41.Fc 42.Sh DESCRIPTION 43The 44.Fn strtonum 45and 46.Fn strtonumx 47functions convert the string in 48.Fa nptr 49to a 50.Vt "long long" 51value. 52These functions were designed to facilitate safe, robust programming and 53overcome the shortcomings of the 54.Xr atoi 3 55and 56.Xr strtol 3 57family of interfaces. 58.Pp 59The string may begin with an arbitrary amount of whitespace 60.Pq as determined by Xr isspace 3 61followed by a single optional 62.Ql + 63or 64.Ql - 65sign. 66.Pp 67The remainder of the string is converted to a 68.Vt "long long" 69value according to base 10 70.Pq for Fn strtonum 71or the provided base 72.Pq for Fn strtonumx . 73.Pp 74The value obtained is then checked against the provided 75.Fa minval 76and 77.Fa maxval 78bounds. 79If 80.Fa errstr 81is non-null, 82.Fn strtonum 83and 84.Fn strtonumx 85store an error string in 86.Fa *errstr 87indicating the failure. 88.Pp 89For 90.Fn strtonumx 91the value of 92.Ar base 93is interpreted in the same way as described in 94.Xr strtoll 3 . 95In particular, if the value of 96.Ar base 97is 0, then the expected form of 98.Ar nptr 99is that of a decimal constant, octal constant or hexadecimal constant, any of 100which may be preceded by a + or - sign. 101.Sh RETURN VALUES 102The 103.Fn strtonum 104and 105.Fn strtonumx 106functions return the result of the conversion, 107unless the value would exceed the provided bounds or is invalid. 108On error, 0 is returned, 109.Va errno 110is set, and 111.Fa errstr 112will point to an error message. 113On success, 114.Fa *errstr 115will be set to 116.Dv NULL ; 117this fact can be used to differentiate 118a successful return of 0 from an error. 119.Sh EXAMPLES 120Using 121.Fn strtonum 122and 123.Fn strtonumx 124correctly is meant to be simpler than the alternative functions. 125.Bd -literal -offset indent 126int iterations; 127const char *errstr; 128 129iterations = strtonum(optarg, 1, 64, &errstr); 130if (errstr != NULL) 131 errx(1, "number of iterations is %s: %s", errstr, optarg); 132.Ed 133.Pp 134The above example will guarantee that the value of iterations is between 1351 and 64 (inclusive). 136.Sh ERRORS 137.Bl -tag -width Er 138.It Bq Er ERANGE 139The given string was out of range. 140.It Bq Er EINVAL 141The given string did not consist solely of digit characters 142.Pq for Fn strtonum , 143or characters which are valid in the given base 144.Pq for Fn strtonumx . 145.It Bq Er EINVAL 146The supplied 147.Fa minval 148was larger than 149.Fa maxval . 150.El 151.Pp 152If an error occurs, 153.Fa errstr 154will be set to one of the following strings: 155.Pp 156.Bl -tag -width ".Li too large" -compact 157.It Qq too large 158The result was larger than the provided maximum value. 159.It Qq too small 160The result was smaller than the provided minimum value. 161.It Qq invalid 162The string did not consist solely of characters valid in the specified base 163.Pq or base 10 for Fn strtonum . 164.It Qq unparsable; invalid base specified 165The specified base was outside the permitted range. 166.El 167.Sh SEE ALSO 168.Xr atof 3 , 169.Xr atoi 3 , 170.Xr atol 3 , 171.Xr atoll 3 , 172.Xr sscanf 3 , 173.Xr strtod 3 , 174.Xr strtol 3 , 175.Xr strtoul 3 176.Sh STANDARDS 177The 178.Fn strtonum 179function is a 180.Bx 181extension. 182The existing alternatives, such as 183.Xr atoi 3 184and 185.Xr strtol 3 , 186are either impossible or difficult to use safely. 187.Sh HISTORY 188The 189.Fn strtonum 190function first appeared in 191.Ox 3.6 . 192The 193.Fn strtonumx 194function first appeared in illumos in 2023. 195