1.\" $OpenBSD: strtonum.3,v 1.5 2004/05/06 06:19:01 tedu Exp $ 2.\" $DragonFly: src/lib/libc/stdlib/strtonum.3,v 1.3 2005/08/01 01:49:16 swildner 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 July 25, 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 unsigned long long 28.Fo strtonum 29.Fa "const char *nptr" 30.Fa "long long minval" 31.Fa "unsigned 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 an 40.Li unsigned long long 41value. 42Negative values may be obtained by casting the result. 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 an 62.Li unsigned 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 and 83.Fa errstr 84will point to an error message. 85.Sh EXAMPLES 86Using 87.Fn strtonum 88correctly is meant to be simpler than the alternative functions. 89.Bd -literal -offset indent 90int iterations; 91const char *errstr; 92 93iterations = strtonum(optarg, 1, 64, &errstr); 94if (errstr) 95 errx(1, "number of iterations is %s: %s", errstr, optarg); 96.Ed 97.Pp 98The above example will guarantee that the value of iterations is between 991 and 64. 100.Sh ERRORS 101.Bl -tag -width Er 102.It Bq Er ERANGE 103The given string was out of range. 104.It Bq Er EINVAL 105The given string did not consist solely of digit characters. 106.El 107.Pp 108If an error occurs, errstr will be set to one of the following strings. 109.Bl -tag -width "too large" 110.It "too large" 111The result was larger than the provided maximum value. 112.It "too small" 113The result was smaller than the provided minimum value. 114.It "invalid" 115The string did not consist solely of digit characters. 116.El 117.Sh SEE ALSO 118.Xr atof 3 , 119.Xr atoi 3 , 120.Xr atol 3 , 121.Xr atoll 3 , 122.Xr sscanf 3 , 123.Xr strtod 3 , 124.Xr strtol 3 , 125.Xr strtoul 3 126.Sh STANDARDS 127.Fn strtonum 128was originally implemented as an extension on 129.Ox . 130The existing alternatives, such as 131.Xr atoi 3 132and 133.Xr strtol 3 134are either impossible or difficult to use safely. 135