14585130bSYuri Pankov.\" 24585130bSYuri Pankov.\" Copyright (c) 2004 Ted Unangst 3*223750d9SAndy Fiddaman.\" Copyright 2023 Oxide Computer Company 44585130bSYuri Pankov.\" 54585130bSYuri Pankov.\" Permission to use, copy, modify, and distribute this software for any 64585130bSYuri Pankov.\" purpose with or without fee is hereby granted, provided that the above 74585130bSYuri Pankov.\" copyright notice and this permission notice appear in all copies. 84585130bSYuri Pankov.\" 94585130bSYuri Pankov.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 104585130bSYuri Pankov.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 114585130bSYuri Pankov.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 124585130bSYuri Pankov.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 134585130bSYuri Pankov.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 144585130bSYuri Pankov.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 154585130bSYuri Pankov.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 164585130bSYuri Pankov.\" 17*223750d9SAndy Fiddaman.Dd August 19, 2023 184585130bSYuri Pankov.Dt STRTONUM 3C 194585130bSYuri Pankov.Os 204585130bSYuri Pankov.Sh NAME 21*223750d9SAndy Fiddaman.Nm strtonum , 22*223750d9SAndy Fiddaman.Nm strtonumx 234585130bSYuri Pankov.Nd reliably convert string value to an integer 244585130bSYuri Pankov.Sh LIBRARY 254585130bSYuri Pankov.Lb libc 264585130bSYuri Pankov.Sh SYNOPSIS 274585130bSYuri Pankov.In stdlib.h 284585130bSYuri Pankov.Ft long long 294585130bSYuri Pankov.Fo strtonum 304585130bSYuri Pankov.Fa "const char *nptr" 314585130bSYuri Pankov.Fa "long long minval" 324585130bSYuri Pankov.Fa "long long maxval" 334585130bSYuri Pankov.Fa "const char **errstr" 344585130bSYuri Pankov.Fc 35*223750d9SAndy Fiddaman.Ft long long 36*223750d9SAndy Fiddaman.Fo strtonumx 37*223750d9SAndy Fiddaman.Fa "const char *nptr" 38*223750d9SAndy Fiddaman.Fa "long long minval" 39*223750d9SAndy Fiddaman.Fa "long long maxval" 40*223750d9SAndy Fiddaman.Fa "const char **errstr" 41*223750d9SAndy Fiddaman.Fa "int base" 42*223750d9SAndy Fiddaman.Fc 434585130bSYuri Pankov.Sh DESCRIPTION 444585130bSYuri PankovThe 454585130bSYuri Pankov.Fn strtonum 46*223750d9SAndy Fiddamanand 47*223750d9SAndy Fiddaman.Fn strtonumx 48*223750d9SAndy Fiddamanfunctions convert the string in 494585130bSYuri Pankov.Fa nptr 504585130bSYuri Pankovto a 514585130bSYuri Pankov.Li long long 524585130bSYuri Pankovvalue. 53*223750d9SAndy FiddamanThese functions were designed to facilitate safe, robust programming and 54*223750d9SAndy Fiddamanovercome the shortcomings of the 554585130bSYuri Pankov.Xr atoi 3C 564585130bSYuri Pankovand 574585130bSYuri Pankov.Xr strtol 3C 584585130bSYuri Pankovfamily of interfaces. 594585130bSYuri Pankov.Pp 604585130bSYuri PankovThe string may begin with an arbitrary amount of whitespace 614585130bSYuri Pankov.Pq as determined by Xr isspace 3C 624585130bSYuri Pankovfollowed by a single optional 634585130bSYuri Pankov.Ql + 644585130bSYuri Pankovor 654585130bSYuri Pankov.Ql - 664585130bSYuri Pankovsign. 674585130bSYuri Pankov.Pp 684585130bSYuri PankovThe remainder of the string is converted to a 694585130bSYuri Pankov.Li long long 70*223750d9SAndy Fiddamanvalue according to base 10 71*223750d9SAndy Fiddaman.Pq for Fn strtonum 72*223750d9SAndy Fiddamanor the provided base 73*223750d9SAndy Fiddaman.Pq for Fn strtonumx . 744585130bSYuri Pankov.Pp 754585130bSYuri PankovThe value obtained is then checked against the provided 764585130bSYuri Pankov.Fa minval 774585130bSYuri Pankovand 784585130bSYuri Pankov.Fa maxval 794585130bSYuri Pankovbounds. 804585130bSYuri PankovIf 814585130bSYuri Pankov.Fa errstr 824585130bSYuri Pankovis non-null, 834585130bSYuri Pankov.Fn strtonum 84*223750d9SAndy Fiddamanand 85*223750d9SAndy Fiddaman.Fn strtonumx 86*223750d9SAndy Fiddamanstore an error string in 874585130bSYuri Pankov.Fa errstr 884585130bSYuri Pankovindicating the failure. 89*223750d9SAndy Fiddaman.Pp 90*223750d9SAndy FiddamanFor 91*223750d9SAndy Fiddaman.Fn strtonumx 92*223750d9SAndy Fiddamanthe value of 93*223750d9SAndy Fiddaman.Ar base 94*223750d9SAndy Fiddamanis interpreted in the same way as described in 95*223750d9SAndy Fiddaman.Xr strtoll 3C . 96*223750d9SAndy FiddamanIn particular, if the value of 97*223750d9SAndy Fiddaman.Ar base 98*223750d9SAndy Fiddamanis 0, then the expected form of 99*223750d9SAndy Fiddaman.Ar nptr 100*223750d9SAndy Fiddamanis that of a decimal constant, octal constant or hexadecimal constant, any of 101*223750d9SAndy Fiddamanwhich may be preceded by a + or - sign. 1024585130bSYuri Pankov.Sh RETURN VALUES 1034585130bSYuri PankovThe 1044585130bSYuri Pankov.Fn strtonum 1054585130bSYuri Pankovfunction returns the result of the conversion, 1064585130bSYuri Pankovunless the value would exceed the provided bounds or is invalid. 1074585130bSYuri PankovOn error, 0 is returned, 1084585130bSYuri Pankov.Va errno 1094585130bSYuri Pankovis set, and 1104585130bSYuri Pankov.Fa errstr 1114585130bSYuri Pankovwill point to an error message. 1124585130bSYuri Pankov.Fa errstr 1134585130bSYuri Pankovwill be set to 1144585130bSYuri Pankov.Dv NULL 1154585130bSYuri Pankovon success; this fact can be used to differentiate a successful return of 0 from 1164585130bSYuri Pankovan error. 1174585130bSYuri Pankov.Sh EXAMPLES 1184585130bSYuri PankovUsing 1194585130bSYuri Pankov.Fn strtonum 1204585130bSYuri Pankovcorrectly is meant to be simpler than the alternative functions. 1214585130bSYuri Pankov.Bd -literal -offset indent 1224585130bSYuri Pankovint iterations; 1234585130bSYuri Pankovconst char *errstr; 1244585130bSYuri Pankov 1254585130bSYuri Pankoviterations = strtonum(optarg, 1, 64, &errstr); 1264585130bSYuri Pankovif (errstr != NULL) 1274585130bSYuri Pankov errx(1, "number of iterations is %s: %s", errstr, optarg); 1284585130bSYuri Pankov.Ed 1294585130bSYuri Pankov.Pp 1304585130bSYuri PankovThe above example will guarantee that the value of iterations is between 1314585130bSYuri Pankov1 and 64 1324585130bSYuri Pankov.Pq inclusive . 1334585130bSYuri Pankov.Sh ERRORS 134*223750d9SAndy FiddamanThe 135*223750d9SAndy Fiddaman.Fn strtonum 136*223750d9SAndy Fiddamanand 137*223750d9SAndy Fiddaman.Fn strtonumx 138*223750d9SAndy Fiddamanfunctions will fail if: 1394585130bSYuri Pankov.Bl -tag -width Er 1404585130bSYuri Pankov.It Er ERANGE 141*223750d9SAndy FiddamanThe value to be returned falls outside of the specified range. 1424585130bSYuri Pankov.It Er EINVAL 1434585130bSYuri Pankov.Ar minval 1444585130bSYuri Pankovwas larger than 1454585130bSYuri Pankov.Ar maxval . 1464585130bSYuri Pankov.El 1474585130bSYuri Pankov.Pp 148*223750d9SAndy FiddamanThe 149*223750d9SAndy Fiddaman.Fn strtonum 150*223750d9SAndy Fiddamanfunction will fail if: 151*223750d9SAndy Fiddaman.Bl -tag -width Er 152*223750d9SAndy Fiddaman.It Er EINVAL 153*223750d9SAndy FiddamanThe given string did not consist solely of digit characters. 154*223750d9SAndy Fiddaman.El 155*223750d9SAndy Fiddaman.Pp 156*223750d9SAndy FiddamanThe 157*223750d9SAndy Fiddaman.Fn strtonumx 158*223750d9SAndy Fiddamanfunction will fail if: 159*223750d9SAndy Fiddaman.Bl -tag -width Er 160*223750d9SAndy Fiddaman.It Er EINVAL 161*223750d9SAndy FiddamanThe specified base was invalid, or the given string did not consist solely of 162*223750d9SAndy Fiddamancharacters which are valid in that base. 163*223750d9SAndy Fiddaman.El 164*223750d9SAndy Fiddaman.Pp 1654585130bSYuri PankovIf an error occurs, 1664585130bSYuri Pankov.Fa errstr 1674585130bSYuri Pankovwill be set to one of the following strings: 1684585130bSYuri Pankov.Pp 1694585130bSYuri Pankov.Bl -tag -width "too largeXX" -compact 1704585130bSYuri Pankov.It Qq too large 1714585130bSYuri PankovThe result was larger than the provided maximum value. 1724585130bSYuri Pankov.It Qq too small 1734585130bSYuri PankovThe result was smaller than the provided minimum value. 1744585130bSYuri Pankov.It Qq invalid 175*223750d9SAndy FiddamanThe string did not consist solely of characters valid in the specified base 176*223750d9SAndy Fiddaman.Pq or base 10 for Fn strtonum . 177*223750d9SAndy Fiddaman.It Qq unparsable; invalid base specified 178*223750d9SAndy FiddamanThe specified base was outside the permitted range. 1794585130bSYuri Pankov.El 1804585130bSYuri Pankov.Sh INTERFACE STABILITY 1814585130bSYuri Pankov.Sy Committed . 1824585130bSYuri Pankov.Sh MT-LEVEL 1834585130bSYuri Pankov.Sy Safe . 1844585130bSYuri Pankov.Sh SEE ALSO 1854585130bSYuri Pankov.Xr atof 3C , 1864585130bSYuri Pankov.Xr atoi 3C , 1874585130bSYuri Pankov.Xr atol 3C , 1884585130bSYuri Pankov.Xr atoll 3C , 1894585130bSYuri Pankov.Xr sscanf 3C , 1904585130bSYuri Pankov.Xr strtod 3C , 1914585130bSYuri Pankov.Xr strtol 3C , 192*223750d9SAndy Fiddaman.Xr strtoll 3C , 1934585130bSYuri Pankov.Xr strtoul 3C 1944585130bSYuri Pankov.Sh STANDARDS 1954585130bSYuri Pankov.Fn strtonum 1964585130bSYuri Pankovis an 1974585130bSYuri Pankov.Ox 1984585130bSYuri Pankovextension. 1994585130bSYuri PankovThe existing alternatives, such as 2004585130bSYuri Pankov.Xr atoi 3C 2014585130bSYuri Pankovand 2024585130bSYuri Pankov.Xr strtol 3C , 2034585130bSYuri Pankovare either impossible or difficult to use safely. 204*223750d9SAndy Fiddaman.Pp 205*223750d9SAndy Fiddaman.Fn strtonumx 206*223750d9SAndy Fiddamanis an illumos extension. 207