Module Name: src
Committed By: christos
Date: Fri Jan 16 18:37:21 UTC 2015
Modified Files:
src/lib/libc/stdlib: Makefile.inc strtol.3 strtoul.3
Log Message:
strtoi and strtou additions
To generate a diff of this commit:
cvs rdiff -u -r1.83 -r1.84 src/lib/libc/stdlib/Makefile.inc
cvs rdiff -u -r1.26 -r1.27 src/lib/libc/stdlib/strtol.3
cvs rdiff -u -r1.25 -r1.26 src/lib/libc/stdlib/strtoul.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/stdlib/Makefile.inc
diff -u src/lib/libc/stdlib/Makefile.inc:1.83 src/lib/libc/stdlib/Makefile.inc:1.84
--- src/lib/libc/stdlib/Makefile.inc:1.83 Wed Dec 10 11:55:54 2014
+++ src/lib/libc/stdlib/Makefile.inc Fri Jan 16 13:37:21 2015
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile.inc,v 1.83 2014/12/10 16:55:54 pooka Exp $
+# $NetBSD: Makefile.inc,v 1.84 2015/01/16 18:37:21 christos Exp $
# from: @(#)Makefile.inc 8.3 (Berkeley) 2/4/95
# stdlib sources
@@ -13,6 +13,7 @@ SRCS+= _env.c _rand48.c \
nrand48.c putenv.c qabs.c qdiv.c qsort.c posix_openpt.c pty.c \
quick_exit.c radixsort.c rand.c rand_r.c random.c remque.c \
seed48.c setenv.c srand48.c strsuftoll.c \
+ strtoi.c strtou.c \
strtoimax.c strtol.c strtoll.c strtoq.c strtoul.c strtoull.c \
strtoumax.c strtouq.c system.c tdelete.c tfind.c tsearch.c twalk.c \
unsetenv.c strfmon.c
@@ -86,7 +87,9 @@ MLINKS+=strtod.3 strtof.3 strtod.3 strto
MLINKS+=strtol.3 strtoimax.3
MLINKS+=strtol.3 strtoll.3
MLINKS+=strtol.3 strtoq.3
+MLINKS+=strtol.3 strtoi.3
MLINKS+=strtoul.3 strtoull.3
MLINKS+=strtoul.3 strtoumax.3
MLINKS+=strtoul.3 strtouq.3
+MLINKS+=strtoul.3 strtou.3
MLINKS+=tsearch.3 tfind.3 tsearch.3 twalk.3 tsearch.3 tdelete.3
Index: src/lib/libc/stdlib/strtol.3
diff -u src/lib/libc/stdlib/strtol.3:1.26 src/lib/libc/stdlib/strtol.3:1.27
--- src/lib/libc/stdlib/strtol.3:1.26 Thu Jul 23 09:38:57 2009
+++ src/lib/libc/stdlib/strtol.3 Fri Jan 16 13:37:21 2015
@@ -1,4 +1,4 @@
-.\" $NetBSD: strtol.3,v 1.26 2009/07/23 13:38:57 wiz Exp $
+.\" $NetBSD: strtol.3,v 1.27 2015/01/16 18:37:21 christos Exp $
.\"
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -33,10 +33,11 @@
.\"
.\" from: @(#)strtol.3 8.1 (Berkeley) 6/4/93
.\"
-.Dd July 23, 2009
+.Dd December 27, 2014
.Dt STRTOL 3
.Os
.Sh NAME
+.Nm strtoi ,
.Nm strtol ,
.Nm strtoll ,
.Nm strtoimax ,
@@ -53,6 +54,8 @@
.Fn strtoll "const char * restrict nptr" "char ** restrict endptr" "int base"
.Pp
.In inttypes.h
+.Ft intmax_t
+.Fn strtoi "const char * restrict nptr" "char ** restrict endptr" "int base" "intmax_t lo" "intmax_t hi" "int *rerror"
.Ft intmax_t
.Fn strtoimax "const char * restrict nptr" "char ** restrict endptr" "int base"
.Pp
@@ -87,6 +90,27 @@ to an
.Ft intmax_t
value.
The
+.Fn strtoi
+function
+is using internally
+.Fn strtoimax
+and ensures that the result is always in the range [
+.Fa lo ..
+.Fa hi
+].
+In adddition it always places
+.Dv 0
+on success or an error value in the
+.Fa rerror
+argument, avoiding the
+.Dv errno
+gymnastics the other functions require.
+The
+.Fa rerror
+argument can be
+.Dv NULL
+if errors are to be ignored.
+The
.Fn strtoq
function
converts the string in
@@ -156,6 +180,15 @@ is
on return, the entire string was valid.)
.Sh RETURN VALUES
The
+.Fn strtoi
+function
+always returns the closest value in the range specified by
+the
+.Fa lo
+and
+.Fa hi
+arguments.
+The
.Fn strtol
function
returns the result of the conversion,
@@ -200,6 +233,21 @@ is left unchanged.
This behavior (which is unlike most library functions) is guaranteed
by the pertinent standards.
.Sh EXAMPLES
+The
+.Fn strtoi
+function is the simplest to use:
+.Bd -literal -offset indent
+int e;
+intmax_t lval = strtoi(buf, NULL, 0, 1, 99, &e);
+if (e)
+ warn("conversion of `%s' to a number failed, using %jd",
+ buf, lval);
+.Ed
+.Pp
+This will always return a number in
+.Dv [1..99]
+range no matter what the input is, and warn if the conversion failed.
+.Pp
Because the return value of
.Fn strtol
cannot be used unambiguously to detect an error,
@@ -269,12 +317,31 @@ is not between 2 and 36 and does not con
.It Bq Er ERANGE
The given string was out of range; the value converted has been clamped.
.El
+.Pp
+In addition to the above errors
+.Fn strtoi
+returns:
+.Bl -tag -width Er
+.It Bq Er ECANCELED
+The string did not contain any characters that could be converted.
+.It Bq Er ENOTSUP
+The string contained non-numeric characters that did not get converted.
+In this case,
+.Fa endptr
+points to the first unconverted character.
+.It Bq Er ERANGE
+The range given was invalid, i.e.
+.Fa lo
+\*[Gt]
+.Fa hi .
+.El
.Sh SEE ALSO
.Xr atof 3 ,
.Xr atoi 3 ,
.Xr atol 3 ,
.Xr atoll 3 ,
.Xr strtod 3 ,
+.Xr strtou 3 ,
.Xr strtoul 3 ,
.Xr strtoull 3 ,
.Xr strtoumax 3
@@ -290,5 +357,9 @@ and
.Fn strtoimax
functions conform to
.St -isoC-99 .
+The
+.Fn strtoi
+function appeared in
+.Nx 8 .
.Sh BUGS
Ignores the current locale.
Index: src/lib/libc/stdlib/strtoul.3
diff -u src/lib/libc/stdlib/strtoul.3:1.25 src/lib/libc/stdlib/strtoul.3:1.26
--- src/lib/libc/stdlib/strtoul.3:1.25 Wed Dec 2 07:50:27 2009
+++ src/lib/libc/stdlib/strtoul.3 Fri Jan 16 13:37:21 2015
@@ -1,4 +1,4 @@
-.\" $NetBSD: strtoul.3,v 1.25 2009/12/02 12:50:27 pooka Exp $
+.\" $NetBSD: strtoul.3,v 1.26 2015/01/16 18:37:21 christos Exp $
.\"
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -33,10 +33,11 @@
.\"
.\" from: @(#)strtoul.3 8.1 (Berkeley) 6/4/93
.\"
-.Dd December 2, 2009
+.Dd December 27, 2014
.Dt STRTOUL 3
.Os
.Sh NAME
+.Nm strtou ,
.Nm strtoul ,
.Nm strtoull ,
.Nm strtoumax ,
@@ -53,6 +54,8 @@
.Fn strtoull "const char * restrict nptr" "char ** restrict endptr" "int base"
.Pp
.In inttypes.h
+.Ft uintmax_t
+.Fn strtou "const char * restrict nptr" "char ** restrict endptr" "int base" "uintmax_t lo" "uintmax_t hi" "int *rerror"
.Ft uintmax_t
.Fn strtoumax "const char * restrict nptr" "char ** restrict endptr" "int base"
.Pp
@@ -86,6 +89,26 @@ converts the string in
to an
.Ft uintmax_t
value.
+.Fn strtou
+function
+is using internally
+.Fn strtoumax
+and ensures that the result is always in the range [
+.Fa lo ..
+.Fa hi
+].
+In adddition it always places
+.Dv 0
+on success or an error value in the
+.Fa rerror
+argument, avoiding the
+.Dv errno
+gymnastics the other functions require.
+The
+.Fa rerror
+argument can be
+.Dv NULL
+if errors are to be ignored.
The
.Fn strtouq
function
@@ -157,6 +180,15 @@ is
on return, the entire string was valid.)
.Sh RETURN VALUES
The
+.Fn strtou
+function
+always returns the closest value in the range specified by
+the
+.Fa lo
+and
+.Fa hi
+arguments.
+The
.Fn strtoul
function
returns either the result of the conversion
@@ -201,6 +233,21 @@ is left unchanged.
This behavior (which is unlike most library functions) is guaranteed
by the pertinent standards.
.Sh EXAMPLES
+The
+.Fn strtou
+function is the simplest to use:
+.Bd -literal -offset indent
+int e;
+uintmax_t lval = strtou(buf, NULL, 0, 1, 99, &e);
+if (e)
+ warn("conversion of `%s' to a number failed, using %ju",
+ buf, lval);
+.Ed
+.Pp
+This will always return a number in
+.Dv [1..99]
+range no matter what the input is, and warn if the conversion failed.
+.Pp
Because the return value of
.Fn strtoul
cannot be used unambiguously to detect an error,
@@ -243,7 +290,26 @@ is not between 2 and 36 and does not con
.It Bq Er ERANGE
The given string was out of range; the value converted has been clamped.
.El
+.Pp
+In addition to the above errors
+.Fn strtou
+returns:
+.Bl -tag -width Er
+.It Bq Er ECANCELED
+The string did not contain any characters that could be converted.
+.It Bq Er ENOTSUP
+The string contained non-numeric characters that did not get converted.
+In this case,
+.Fa endptr
+points to the first unconverted character.
+.It Bq Er ERANGE
+The range given was invalid, i.e.
+.Fa lo
+\*[Gt]
+.Fa hi .
+.El
.Sh SEE ALSO
+.Xr strtoi 3 ,
.Xr strtoimax 3 ,
.Xr strtol 3 ,
.Xr strtoll 3
@@ -259,5 +325,9 @@ and
.Fn strtoumax
functions conform to
.St -isoC-99 .
+The
+.Fn strtou
+function appeared in
+.Nx 8 .
.Sh BUGS
Ignores the current locale.
