1.\" $DragonFly: src/lib/libc/stdlib/strtonum.3,v 1.6 2007/08/18 20:48:47 swildner 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 LIBRARY 25.Lb libc 26.Sh SYNOPSIS 27.In stdlib.h 28.Ft long long 29.Fo strtonum 30.Fa "const char *nptr" 31.Fa "long long minval" 32.Fa "long long maxval" 33.Fa "const char **errstr" 34.Fc 35.Sh DESCRIPTION 36The 37.Fn strtonum 38function converts the string in 39.Fa nptr 40to a 41.Li long long 42value. 43The 44.Fn strtonum 45function was designed to facilitate safe, robust programming 46and overcome the shortcomings of the 47.Xr atoi 3 48and 49.Xr strtol 3 50family of interfaces. 51.Pp 52The string may begin with an arbitrary amount of whitespace 53(as determined by 54.Xr isspace 3 ) 55followed by a single optional 56.Ql + 57or 58.Ql - 59sign. 60.Pp 61The remainder of the string is converted to a 62.Li long long 63value according to base 10. 64.Pp 65The value obtained is then checked against the provided 66.Fa minval 67and 68.Fa maxval 69bounds. 70If 71.Fa errstr 72is non-null, 73.Fn strtonum 74stores an error string in 75.Fa *errstr 76indicating the failure. 77.Sh RETURN VALUES 78The 79.Fn strtonum 80function returns the result of the conversion, 81unless the value would exceed the provided bounds or is invalid. 82On error, 0 is returned, 83.Va errno 84is set, and 85.Fa errstr 86will point to an error message. 87.Fa *errstr 88will be set to 89.Dv NULL 90on success; 91this fact can be used to differentiate 92a successful return of 0 from an error. 93.Sh EXAMPLES 94Using 95.Fn strtonum 96correctly is meant to be simpler than the alternative functions. 97.Bd -literal -offset indent 98int iterations; 99const char *errstr; 100 101iterations = strtonum(optarg, 1, 64, &errstr); 102if (errstr) 103 errx(1, "number of iterations is %s: %s", errstr, optarg); 104.Ed 105.Pp 106The above example will guarantee that the value of iterations is between 1071 and 64 (inclusive). 108.Sh ERRORS 109.Bl -tag -width Er 110.It Bq Er ERANGE 111The given string was out of range. 112.It Bq Er EINVAL 113The given string did not consist solely of digit characters. 114.It Bq Er EINVAL 115.Ar minval 116was larger than 117.Ar 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 "too largeXX" -compact 125.It too large 126The result was larger than the provided maximum value. 127.It too small 128The result was smaller than the provided minimum value. 129.It 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 142.Fn strtonum 143was originally implemented as an extension on 144.Ox . 145The existing alternatives, such as 146.Xr atoi 3 147and 148.Xr strtol 3 149are either impossible or difficult to use safely. 150