1.\" $DragonFly: src/lib/libc/stdlib/strtonum.3,v 1.5 2006/09/28 17:20:45 corecode Exp $ 2.\" $OpenBSD: strtonum.3,v 1.13 2006/04/25 05:15:42 tedu 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.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.Li 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.Li 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. 85.Fa *errstr 86will be set to 87.Dv NULL 88on success; 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) 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 113.Ar minval 114was larger than 115.Ar maxval . 116.El 117.Pp 118If an error occurs, 119.Fa errstr 120will be set to one of the following strings: 121.Pp 122.Bl -tag -width "too largeXX" -compact 123.It too large 124The result was larger than the provided maximum value. 125.It too small 126The result was smaller than the provided minimum value. 127.It invalid 128The string did not consist solely of digit characters. 129.El 130.Sh SEE ALSO 131.Xr atof 3 , 132.Xr atoi 3 , 133.Xr atol 3 , 134.Xr atoll 3 , 135.Xr sscanf 3 , 136.Xr strtod 3 , 137.Xr strtol 3 , 138.Xr strtoul 3 139.Sh STANDARDS 140.Fn strtonum 141was originally implemented as an extension on 142.Ox . 143The existing alternatives, such as 144.Xr atoi 3 145and 146.Xr strtol 3 147are either impossible or difficult to use safely. 148