1.\" $MirOS: src/lib/libc/stdlib/strtonum.3,v 1.3 2005/09/22 20:15:31 tg Exp $ 2.\" $OpenBSD: strtonum.3,v 1.11 2005/04/14 07:58:46 jmc Exp $ 3.\" 4.\" Copyright (c) 2004 Ted Unangst 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd April 29, 2004 19.Dt STRTONUM 3 20.Os 21.Sh NAME 22.Nm strtonum 23.Nd "reliably convert string value to an integer" 24.Sh SYNOPSIS 25.Fd #include <stdlib.h> 26.Fd #include <limits.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.Sh DESCRIPTION 35The 36.Fn strtonum 37function converts the string in 38.Fa nptr 39to a 40.Li long long 41value. 42The 43.Fn strtonum 44function was designed to facilitate safe, robust programming 45and overcome the shortcomings of the 46.Xr atoi 3 47and 48.Xr strtol 3 49family of interfaces. 50.Pp 51The string may begin with an arbitrary amount of whitespace 52(as determined by 53.Xr isspace 3 ) 54followed by a single optional 55.Ql + 56or 57.Ql - 58sign. 59.Pp 60The remainder of the string is converted to a 61.Li long long 62value according to base 10. 63On 64.Mx , 65if the value is prefixed by 66.Sq 0 67or 68.Sq 0x , 69conversion is done according to base 8 or 16, respectively. 70This is a change in the underlying library and only visible 71to the user, not to the programme using 72.Fn strtonum . 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 83stores an error string in 84.Fa *errstr 85indicating the failure. 86.Sh RETURN VALUES 87The 88.Fn strtonum 89function returns the result of the conversion, 90unless the value would exceed the provided bounds or is invalid. 91On error, 0 is returned and 92.Fa errstr 93will point to an error message. 94.Fa *errstr 95will be set to 96.Dv NULL 97on success; 98this fact can be used to differentiate 99a successful return of 0 from an error. 100.Sh EXAMPLES 101Using 102.Fn strtonum 103correctly is meant to be simpler than the alternative functions. 104.Bd -literal -offset indent 105int iterations; 106const char *errstr; 107 108iterations = strtonum(optarg, 1, 64, &errstr); 109if (errstr) 110 errx(1, "number of iterations is %s: %s", errstr, optarg); 111.Ed 112.Pp 113The above example will guarantee that the value of iterations is between 1141 and 64. 115.Sh ERRORS 116.Bl -tag -width Er 117.It Bq Er ERANGE 118The given string was out of range. 119.It Bq Er EINVAL 120The given string did not consist solely of digit characters. 121.It Bq Er EINVAL 122.Ar minval 123was larger than 124.Ar maxval . 125.El 126.Pp 127If an error occurs, 128.Fa errstr 129will be set to one of the following strings: 130.Pp 131.Bl -tag -width "too largeXX" -compact 132.It too large 133The result was larger than the provided maximum value. 134.It too small 135The result was smaller than the provided minimum value. 136.It invalid 137The string did not consist solely of digit characters. 138.El 139.Sh SEE ALSO 140.Xr atof 3 , 141.Xr atoi 3 , 142.Xr atol 3 , 143.Xr atoll 3 , 144.Xr sscanf 3 , 145.Xr strtod 3 , 146.Xr strtol 3 , 147.Xr strtoul 3 148.Sh STANDARDS 149.Fn strtonum 150is an 151.Ox 152extension. 153The existing alternatives, such as 154.Xr atoi 3 155and 156.Xr strtol 3 , 157are either impossible or difficult to use safely. 158.Sh HISTORY 159The 160.Fn strtonum 161function first appeared in 162.Ox 3.6 . 163