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