summaryrefslogtreecommitdiff
path: root/lib/libc/stdlib
diff options
context:
space:
mode:
authorchristos <christos@NetBSD.org>2015-01-18 17:59:36 +0000
committerchristos <christos@NetBSD.org>2015-01-18 17:59:36 +0000
commitd010fbe8c51c709f93aabf068f393ae1bb7bcb13 (patch)
tree7cd9c750c5ede50359e3f8d485fa6d51894a60ad /lib/libc/stdlib
parent9f7f631d862a4fc58736cdeff88dbb2332adb3df (diff)
man page for strtonum.3
Diffstat (limited to 'lib/libc/stdlib')
-rw-r--r--lib/libc/stdlib/Makefile.inc5
-rw-r--r--lib/libc/stdlib/strtonum.3187
2 files changed, 190 insertions, 2 deletions
diff --git a/lib/libc/stdlib/Makefile.inc b/lib/libc/stdlib/Makefile.inc
index e52bd51d69d..f918e425b3e 100644
--- a/lib/libc/stdlib/Makefile.inc
+++ b/lib/libc/stdlib/Makefile.inc
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile.inc,v 1.85 2015/01/16 18:41:33 christos Exp $
+# $NetBSD: Makefile.inc,v 1.86 2015/01/18 17:59:36 christos Exp $
# from: @(#)Makefile.inc 8.3 (Berkeley) 2/4/95
# stdlib sources
@@ -53,7 +53,8 @@ MAN+= a64l.3 abort.3 abs.3 alloca.3 atexit.3 atof.3 atoi.3 atol.3 atoll.3 \
posix_memalign.3 posix_openpt.3 ptsname.3 \
qabs.3 qdiv.3 quick_exit.3 qsort.3 \
radixsort.3 rand48.3 rand.3 random.3 \
- strfmon.3 strsuftoll.3 strtod.3 strtol.3 strtoul.3 system.3 \
+ strfmon.3 strsuftoll.3 strtod.3 strtol.3 strtoul.3 strtonum.3 \
+ system.3 \
tsearch.3 \
unlockpt.3
diff --git a/lib/libc/stdlib/strtonum.3 b/lib/libc/stdlib/strtonum.3
new file mode 100644
index 00000000000..dc7ae1e8909
--- /dev/null
+++ b/lib/libc/stdlib/strtonum.3
@@ -0,0 +1,187 @@
+.\" $NetBSD: strtonum.3,v 1.1 2015/01/18 17:59:36 christos Exp $
+.\" $OpenBSD: strtonum.3,v 1.17 2013/08/14 06:32:28 jmc Exp $
+.\"
+.\" Copyright (c) 2004 Ted Unangst
+.\"
+.\" 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.
+.\"
+.\" 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 $Mdocdate: August 14 2013 $
+.Dt STRTONUM 3
+.Os
+.Sh NAME
+.Nm strtonum
+.Nd reliably convert string value to an integer
+.Sh SYNOPSIS
+.Vt #define _OPENBSD_SOURCE
+.In stdlib.h
+.Ft long long
+.Fo strtonum
+.Fa "const char *nptr"
+.Fa "long long minval"
+.Fa "long long maxval"
+.Fa "const char **errstr"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn strtonum
+function converts the string in
+.Fa nptr
+to a
+.Li long long
+value.
+.Pp
+The string may begin with an arbitrary amount of whitespace
+(as determined by
+.Xr isspace 3 )
+followed by a single optional
+.Ql +
+or
+.Ql -
+sign.
+.Pp
+The remainder of the string is converted to a
+.Li long long
+value according to base 10.
+.Pp
+The value obtained is then checked against the provided
+.Fa minval
+and
+.Fa maxval
+bounds.
+If
+.Fa errstr
+is non-null,
+.Fn strtonum
+stores an error string in
+.Fa *errstr
+indicating the failure.
+.Sh RETURN VALUES
+The
+.Fn strtonum
+function returns the result of the conversion,
+unless the value would exceed the provided bounds or is invalid.
+On error, 0 is returned,
+.Va errno
+is set, and
+.Fa errstr
+will point to an error message.
+.Fa *errstr
+will be set to
+.Dv NULL
+on success;
+this fact can be used to differentiate
+a successful return of 0 from an error.
+.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 (inclusive).
+.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 digit characters.
+.It Bq Er EINVAL
+.Ar minval
+was larger than
+.Ar maxval .
+.El
+.Pp
+If an error occurs,
+.Fa errstr
+will be set to one of the following strings:
+.Pp
+.Bl -tag -width "too largeXX" -compact
+.It Qq too large
+The result was larger than the provided maximum value.
+.It Qq too small
+The result was smaller than the provided minimum value.
+.It Qq invalid
+The string did not consist solely of digit characters.
+.El
+.Sh CAVEATS
+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, however there are problems with the
+.Fn strtonum
+API:
+.Bl -dash
+.It
+will return 0 on failure; 0 might not be in range, so that necessitates an error check even if you want to avoid it
+.It
+does not differentiate 'illegal' returns, so we can't tell the difference between partial and no conversions
+.It
+returns english strings
+.It
+can't set the base, or find where the conversion ended
+.It
+hardcodes long long integer type
+.El
+To overcome the shortcomings of
+.Fn strtonum
+.Nx
+provides
+.Fn strtou 3
+and
+.Fn strtoi 3 .
+.Sh SEE ALSO
+.Xr atof 3 ,
+.Xr atoi 3 ,
+.Xr atol 3 ,
+.Xr atoll 3 ,
+.Xr sscanf 3 ,
+.Xr strtoi 3 ,
+.Xr strtod 3 ,
+.Xr strtol 3 ,
+.Xr strtoll 3 ,
+.Xr strtou 3 ,
+.Xr strtoul 3
+.Xr strtoull 3
+.Sh STANDARDS
+.Fn strtonum
+is an
+.Ox
+extension.
+.Sh HISTORY
+The
+.Fn strtonum
+function first appeared in
+.Ox 3.6 .
+.Fn strtonum
+was redesigned in
+.Nx 8
+as
+.Fn strtoi 3
+and
+.Fn strtou 3 .
+For compatibility reasons it's available since
+.Nx 8
+in the
+.Vt _OPENBSD_SOURCE
+namespace.