1.\" Copyright (c) 2004 Ted Unangst 2.\" 3.\" Permission to use, copy, modify, and distribute this software for any 4.\" purpose with or without fee is hereby granted, provided that the above 5.\" copyright notice and this permission notice appear in all copies. 6.\" 7.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 8.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 10.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 12.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 13.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 14.\" 15.\" $OpenBSD: strtonum.3,v 1.12 2005/10/26 11:37:58 jmc Exp $ 16.\" $FreeBSD$ 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.In stdlib.h 26.In 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.Vt "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.Vt "long long" 62value according to base 10. 63.Pp 64The value obtained is then checked against the provided 65.Fa minval 66and 67.Fa maxval 68bounds. 69If 70.Fa errstr 71is non-null, 72.Fn strtonum 73stores an error string in 74.Fa *errstr 75indicating the failure. 76.Sh RETURN VALUES 77The 78.Fn strtonum 79function returns the result of the conversion, 80unless the value would exceed the provided bounds or is invalid. 81On error, 0 is returned, 82.Va errno 83is set, and 84.Fa errstr 85will point to an error message. 86On success, 87.Fa *errstr 88will be set to 89.Dv NULL ; 90this fact can be used to differentiate 91a successful return of 0 from an error. 92.Sh EXAMPLES 93Using 94.Fn strtonum 95correctly is meant to be simpler than the alternative functions. 96.Bd -literal -offset indent 97int iterations; 98const char *errstr; 99 100iterations = strtonum(optarg, 1, 64, &errstr); 101if (errstr) 102 errx(1, "number of iterations is %s: %s", errstr, optarg); 103.Ed 104.Pp 105The above example will guarantee that the value of iterations is between 1061 and 64 (inclusive). 107.Sh ERRORS 108.Bl -tag -width Er 109.It Bq Er ERANGE 110The given string was out of range. 111.It Bq Er EINVAL 112The given string did not consist solely of digit characters. 113.It Bq Er EINVAL 114The supplied 115.Fa minval 116was larger than 117.Fa maxval . 118.El 119.Pp 120If an error occurs, 121.Fa errstr 122will be set to one of the following strings: 123.Pp 124.Bl -tag -width ".Li too large" -compact 125.It Li "too large" 126The result was larger than the provided maximum value. 127.It Li "too small" 128The result was smaller than the provided minimum value. 129.It Li invalid 130The string did not consist solely of digit characters. 131.El 132.Sh SEE ALSO 133.Xr atof 3 , 134.Xr atoi 3 , 135.Xr atol 3 , 136.Xr atoll 3 , 137.Xr sscanf 3 , 138.Xr strtod 3 , 139.Xr strtol 3 , 140.Xr strtoul 3 141.Sh STANDARDS 142The 143.Fn strtonum 144function is a 145.Bx 146extension. 147The existing alternatives, such as 148.Xr atoi 3 149and 150.Xr strtol 3 , 151are either impossible or difficult to use safely. 152.Sh HISTORY 153The 154.Fn strtonum 155function first appeared in 156.Ox 3.6 . 157