improved man page, with example and error strings, suggested by deraadt@

man help jmc@

src/lib/libc/stdlib/strtonum.3

@@ -1,35 +1,18 @@
-.\" Copyright (c) 1990, 1991 The Regents of the University of California.
-.\" All rights reserved.
+.\" $OpenBSD: strtonum.3,v 1.5 2004/05/06 06:19:01 tedu Exp $
 .\"
-.\" This code is derived from software contributed to Berkeley by
-.\" Chris Torek and the American National Standards Committee X3,
-.\" on Information Processing Systems.
+.\" Copyright (c) 2004 Ted Unangst
 .\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\" 3. Neither the name of the University nor the names of its contributors
-.\"    may be used to endorse or promote products derived from this software
-.\"    without specific prior written permission.
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\"	$OpenBSD: strtonum.3,v 1.4 2004/05/06 04:20:20 deraadt Exp $
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .Dd April 29, 2004
 .Dt STRTONUM 3
@@ -55,8 +38,15 @@ function converts the string in
 to an
 .Li unsigned long long
 value.
-The conversion is done according to base 10.
 Negative values may be obtained by casting the result.
+The
+.Fn strtonum
+function was designed to facilitate safe, robust programming
+and overcome the shortcomings of the
+.Xr atoi 3
+and
+.Xr strtol 3
+family of interfaces.
 .Pp
 The string may begin with an arbitrary amount of whitespace
 (as determined by
@@ -69,9 +59,7 @@ sign.
 .Pp
 The remainder of the string is converted to an
 .Li unsigned long long
-value in the obvious manner,
-stopping at the first character which is not a valid digit
-in the given base.
+value according to base 10.
 .Pp
 The value obtained is then checked against the provided
 .Fa minval
@@ -89,14 +77,41 @@ indicating the failure.
 The
 .Fn strtonum
 function returns the result of the conversion,
-unless the value would underflow or overflow.
-On error, 0 is returned.
+unless the value would exceed the provided bounds or is invalid.
+On error, 0 is returned and
+.Fa errstr
+will point to an error message.
+.Sh EXAMPLES
+Using
+.Fn strtonum
+correctly is meant to be simpler than the alternative functions.
+.Bd -literal -offset indent
+int iterations;
+const char *errstr;
+
+iterations = strtonum(optarg, 1, 64, &errstr);
+if (errstr)
+	errx(1, "number of iterations is %s: %s", errstr, optarg);
+.Ed
+.Pp
+The above example will guarantee that the value of iterations is between
+1 and 64.
 .Sh ERRORS
 .Bl -tag -width Er
 .It Bq Er ERANGE
 The given string was out of range.
 .It Bq Er EINVAL
-The given string did not consist solely of a valid number.
+The given string did not consist solely of digit characters.
+.El
+.Pp
+If an error occurs, errstr will be set to one of the following strings.
+.Bl -tag -width "too large"
+.It "too large"
+The result was larger than the provided maximum value.
+.It "too small"
+The result was smaller than the provided minimum value.
+.It "invalid"
+The string did not consist solely of digit characters.
 .El
 .Sh SEE ALSO
 .Xr atof 3 ,
@@ -112,3 +127,8 @@ The given string did not consist solely of a valid number.
 is an
 .Ox
 extension.
+The existing alternatives, such as
+.Xr atoi 3
+and
+.Xr strtol 3
+are either impossible or difficult to use safely.