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.13 2006/04/25 05:15:42 tedu 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.Ft long long 27.Fo strtonum 28.Fa "const char *nptr" 29.Fa "long long minval" 30.Fa "long long maxval" 31.Fa "const char **errstr" 32.Fc 33.Sh DESCRIPTION 34The 35.Fn strtonum 36function converts the string in 37.Fa nptr 38to a 39.Vt "long long" 40value. 41The 42.Fn strtonum 43function was designed to facilitate safe, robust programming 44and overcome the shortcomings of the 45.Xr atoi 3 46and 47.Xr strtol 3 48family of interfaces. 49.Pp 50The string may begin with an arbitrary amount of whitespace 51(as determined by 52.Xr isspace 3 ) 53followed by a single optional 54.Ql + 55or 56.Ql - 57sign. 58.Pp 59The remainder of the string is converted to a 60.Vt "long long" 61value according to base 10. 62.Pp 63The value obtained is then checked against the provided 64.Fa minval 65and 66.Fa maxval 67bounds. 68If 69.Fa errstr 70is non-null, 71.Fn strtonum 72stores an error string in 73.Fa *errstr 74indicating the failure. 75.Sh RETURN VALUES 76The 77.Fn strtonum 78function returns the result of the conversion, 79unless the value would exceed the provided bounds or is invalid. 80On error, 0 is returned, 81.Va errno 82is set, and 83.Fa errstr 84will point to an error message. 85On success, 86.Fa *errstr 87will be set to 88.Dv NULL ; 89this fact can be used to differentiate 90a successful return of 0 from an error. 91.Sh EXAMPLES 92Using 93.Fn strtonum 94correctly is meant to be simpler than the alternative functions. 95.Bd -literal -offset indent 96int iterations; 97const char *errstr; 98 99iterations = strtonum(optarg, 1, 64, &errstr); 100if (errstr != NULL) 101 errx(1, "number of iterations is %s: %s", errstr, optarg); 102.Ed 103.Pp 104The above example will guarantee that the value of iterations is between 1051 and 64 (inclusive). 106.Sh ERRORS 107.Bl -tag -width Er 108.It Bq Er ERANGE 109The given string was out of range. 110.It Bq Er EINVAL 111The given string did not consist solely of digit characters. 112.It Bq Er EINVAL 113The supplied 114.Fa minval 115was larger than 116.Fa maxval . 117.El 118.Pp 119If an error occurs, 120.Fa errstr 121will be set to one of the following strings: 122.Pp 123.Bl -tag -width ".Li too large" -compact 124.It Li "too large" 125The result was larger than the provided maximum value. 126.It Li "too small" 127The result was smaller than the provided minimum value. 128.It Li invalid 129The string did not consist solely of digit characters. 130.El 131.Sh SEE ALSO 132.Xr atof 3 , 133.Xr atoi 3 , 134.Xr atol 3 , 135.Xr atoll 3 , 136.Xr sscanf 3 , 137.Xr strtod 3 , 138.Xr strtol 3 , 139.Xr strtoul 3 140.Sh STANDARDS 141The 142.Fn strtonum 143function is a 144.Bx 145extension. 146The existing alternatives, such as 147.Xr atoi 3 148and 149.Xr strtol 3 , 150are either impossible or difficult to use safely. 151.Sh HISTORY 152The 153.Fn strtonum 154function first appeared in 155.Ox 3.6 . 156