Module Name: src
Committed By: kre
Date: Wed Jul 24 08:55:09 UTC 2024
Modified Files:
src/distrib/sets/lists/comp: mi
src/lib/libc/stdlib: Makefile.inc strtoi.3
Log Message:
Improve the man for strtoi() (and consequently strtou())
PR lib/58461 PR lib/58453
Improve the wording so it is clearer exactly what strtoi() is
intended to do in various cases.
While here, add, in the most minimalist way possible, the
strtoi_l(), and so also strtou_l(), functions, which seem to
have been previously undocumented.
Do some linguistic gymnastics so that the conversion of the
page from strtoi(3) -> strtou(3) will not generate "an unitmax_t"
which is incorrect, we need "a unitmax_t" - one of those was
easy to fix in the Makefile sed script, the others would have
been more difficult, so reword instead.
To generate a diff of this commit:
cvs rdiff -u -r1.2465 -r1.2466 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.99 -r1.100 src/lib/libc/stdlib/Makefile.inc
cvs rdiff -u -r1.10 -r1.11 src/lib/libc/stdlib/strtoi.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2465 src/distrib/sets/lists/comp/mi:1.2466
--- src/distrib/sets/lists/comp/mi:1.2465 Wed Jul 24 02:36:24 2024
+++ src/distrib/sets/lists/comp/mi Wed Jul 24 08:55:08 2024
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2465 2024/07/24 02:36:24 rin Exp $
+# $NetBSD: mi,v 1.2466 2024/07/24 08:55:08 kre Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -10900,6 +10900,7 @@
./usr/share/man/cat3/strtof.0 comp-c-catman .cat
./usr/share/man/cat3/strtoi.0 comp-c-catman .cat
./usr/share/man/cat3/strtoimax.0 comp-c-catman .cat
+./usr/share/man/cat3/strtoi_l.0 comp-c-catman .cat
./usr/share/man/cat3/strtok.0 comp-c-catman .cat
./usr/share/man/cat3/strtok_r.0 comp-c-catman .cat
./usr/share/man/cat3/strtol.0 comp-c-catman .cat
@@ -10912,6 +10913,7 @@
./usr/share/man/cat3/strtoull.0 comp-c-catman .cat
./usr/share/man/cat3/strtoumax.0 comp-c-catman .cat
./usr/share/man/cat3/strtouq.0 comp-c-catman .cat
+./usr/share/man/cat3/strtou_l.0 comp-c-catman .cat
./usr/share/man/cat3/strunvis.0 comp-c-catman .cat
./usr/share/man/cat3/strunvisx.0 comp-c-catman .cat
./usr/share/man/cat3/strvis.0 comp-c-catman .cat
@@ -19384,6 +19386,7 @@
./usr/share/man/html3/strtof.html comp-c-htmlman html
./usr/share/man/html3/strtoi.html comp-c-htmlman html
./usr/share/man/html3/strtoimax.html comp-c-htmlman html
+./usr/share/man/html3/strtoi_l.html comp-c-htmlman html
./usr/share/man/html3/strtok.html comp-c-htmlman html
./usr/share/man/html3/strtok_r.html comp-c-htmlman html
./usr/share/man/html3/strtol.html comp-c-htmlman html
@@ -19396,6 +19399,7 @@
./usr/share/man/html3/strtoull.html comp-c-htmlman html
./usr/share/man/html3/strtoumax.html comp-c-htmlman html
./usr/share/man/html3/strtouq.html comp-c-htmlman html
+./usr/share/man/html3/strtou_l.html comp-c-htmlman html
./usr/share/man/html3/strunvis.html comp-c-htmlman html
./usr/share/man/html3/strunvisx.html comp-c-htmlman html
./usr/share/man/html3/strvis.html comp-c-htmlman html
@@ -27904,6 +27908,7 @@
./usr/share/man/man3/strtof.3 comp-c-man .man
./usr/share/man/man3/strtoi.3 comp-c-man .man
./usr/share/man/man3/strtoimax.3 comp-c-man .man
+./usr/share/man/man3/strtoi_l.3 comp-c-man .man
./usr/share/man/man3/strtok.3 comp-c-man .man
./usr/share/man/man3/strtok_r.3 comp-c-man .man
./usr/share/man/man3/strtol.3 comp-c-man .man
@@ -27916,6 +27921,7 @@
./usr/share/man/man3/strtoull.3 comp-c-man .man
./usr/share/man/man3/strtoumax.3 comp-c-man .man
./usr/share/man/man3/strtouq.3 comp-c-man .man
+./usr/share/man/man3/strtou_l.3 comp-c-man .man
./usr/share/man/man3/strunvis.3 comp-c-man .man
./usr/share/man/man3/strunvisx.3 comp-c-man .man
./usr/share/man/man3/strvis.3 comp-c-man .man
Index: src/lib/libc/stdlib/Makefile.inc
diff -u src/lib/libc/stdlib/Makefile.inc:1.99 src/lib/libc/stdlib/Makefile.inc:1.100
--- src/lib/libc/stdlib/Makefile.inc:1.99 Fri Jun 7 20:50:13 2024
+++ src/lib/libc/stdlib/Makefile.inc Wed Jul 24 08:55:08 2024
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile.inc,v 1.99 2024/06/07 20:50:13 riastradh Exp $
+# $NetBSD: Makefile.inc,v 1.100 2024/07/24 08:55:08 kre Exp $
# from: @(#)Makefile.inc 8.3 (Berkeley) 2/4/95
# stdlib sources
@@ -65,6 +65,7 @@ MAN+= a64l.3 abort.3 abs.3 alloca.3 atex
strtou.3: strtoi.3
${_MKTARGET_CREATE}
${TOOL_SED} -e s/strtoi/strtou/g -e s/STRTOI/STRTOU/g \
+ -e 's/an intmax_t/a unitmax_t/g' -e 's/strtou 3/strtoi 3/g' \
-e s/intmax_t/uintmax_t/g -e s/%jd/%ju/g ${.ALLSRC} > ${.TARGET}
CLEANFILES += strtou.3
@@ -98,9 +99,11 @@ MLINKS+=radixsort.3 sradixsort.3
MLINKS+=strfmon.3 strfmon_l.3
MLINKS+=strsuftoll.3 strsuftollx.3
MLINKS+=strtod.3 strtof.3 strtod.3 strtold.3
+MLINKS+=strtoi.3 strtoi_l.3
MLINKS+=strtol.3 strtoimax.3
MLINKS+=strtol.3 strtoll.3
MLINKS+=strtol.3 strtoq.3
+MLINKS+=strtou.3 strtou_l.3
MLINKS+=strtoul.3 strtoull.3
MLINKS+=strtoul.3 strtoumax.3
MLINKS+=strtoul.3 strtouq.3
Index: src/lib/libc/stdlib/strtoi.3
diff -u src/lib/libc/stdlib/strtoi.3:1.10 src/lib/libc/stdlib/strtoi.3:1.11
--- src/lib/libc/stdlib/strtoi.3:1.10 Sat Feb 10 18:43:51 2024
+++ src/lib/libc/stdlib/strtoi.3 Wed Jul 24 08:55:08 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: strtoi.3,v 1.10 2024/02/10 18:43:51 andvar Exp $
+.\" $NetBSD: strtoi.3,v 1.11 2024/07/24 08:55:08 kre Exp $
.\"
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -36,11 +36,12 @@
.\" Created by Kamil Rytarowski, based on ID:
.\" NetBSD: strtol.3,v 1.31 2015/03/11 09:57:35 wiz Exp
.\"
-.Dd January 20, 2024
+.Dd July 24, 2024
.Dt STRTOI 3
.Os
.Sh NAME
-.Nm strtoi
+.Nm strtoi ,
+.Nm strtoi_l
.Nd convert a string value to an intmax_t integer
.Sh LIBRARY
.Lb libc
@@ -55,34 +56,51 @@
.Fa "intmax_t hi"
.Fa "int *rstatus"
.Fc
+.In locale.h
+.Ft intmax_t
+.Fo strtoi_l
+.Fa "const char * restrict nptr"
+.Fa "char ** restrict endptr"
+.Fa "int base"
+.Fa "intmax_t lo"
+.Fa "intmax_t hi"
+.Fa "int *rstatus"
+.Fa "locale_t loc"
+.Fc
.Sh DESCRIPTION
The
.Fn strtoi
-function converts the string in
-.Fa nptr
-to an
+generates the
.Ft intmax_t
-value.
+result value equivalent to the numeric string in
+.Fa nptr .
The
.Fn strtoi
-function uses internally
+function internally uses
.Xr strtoimax 3
-and ensures that the result is always in the range [
-.Fa lo ..
-.Fa hi
-].
-In addition it always places
+and then ensures that the result is in the range
+.Bq Fa lo No .. Fa hi .
+In addition it places
+a conversion status indicator,
.Dv 0
-on success or a conversion status in the
+if fully successful,
+in the integer addressed by the
.Fa rstatus
-argument, avoiding the
+argument, if that is not NULL, allowing the
.Dv errno
-gymnastics the other functions require.
+gymnastics that other similar functions require to be avoided.
The
.Fa rstatus
argument can be
.Dv NULL
-if conversion status is to be ignored.
+if the conversion status is to be ignored.
+.Pp
+The operation of
+.Fn strtoi
+is unspecified if
+.Fa lo
+is greater than
+.Fa hi .
.Pp
The string may begin with an arbitrary amount of white space
(as determined by
@@ -100,6 +118,7 @@ the string may then include a
or
.Ql 0X
prefix,
+after which there must immediately follow at least one hexadecimal digit,
and the number will be read in base 16; otherwise,
.\" if the
.\" .Fa base
@@ -116,9 +135,9 @@ is taken as 10 (decimal) unless the next
.Ql 0 ,
in which case it is taken as 8 (octal).
.Pp
-The remainder of the string is converted to an
+The remainder of the string is converted to the
.Em intmax_t
-value in the obvious manner,
+result in the obvious manner,
stopping at the end of the string
or at the first character which is not a valid digit
in the given base.
@@ -133,11 +152,15 @@ representing 35.)
.Pp
If
.Fa endptr
-is non-nil,
+is not NULL,
.Fn strtoi
-stores the address of the first invalid character in
+stores the address of the first character after those
+which were converted in
.Fa *endptr .
If there were no digits at all, however,
+or if the
+.Fa base
+is invalid,
.Fn strtoi
stores the original value of
.Fa nptr
@@ -152,24 +175,46 @@ but
is
.Ql \e0
on return, the entire string was valid.)
+Note that converting an out of range value has no
+impact upon the value placed into
+.Fa *endptr .
+.Pp
+The
+.Fn strtoi_l
+function is identical, except uses the locale given by
+.Fa loc
+rather than the current locale, when determining what is white space to
+be skipped before the conversion begins.
.Sh RETURN VALUES
The
.Fn strtoi
-function
-always returns the closest value in the range specified by
-the
+function,
+returns the converted value,
+or the closest value in the range specified by the
.Fa lo
and
.Fa hi
-arguments.
+arguments, if the value converted was outside that range.
+If
+.Fa lo
+is equal to
+.Fa hi
+and no overriding error occurs,
+that value will always be returned.
.Pp
The
.Va errno
-value is guaranteed to be left unchanged.
+value from
+.In errno.h ,
+is guaranteed to be left unchanged.
.Pp
-Errors are stored as the conversion status in the
+Errors are stored as the conversion status error indicator,
+taken from a subset of the values from
+.In errno.h
+in the
.Fa rstatus
-argument.
+argument, if that was not given as a NULL pointer.
+See the ERRORS section below for the possible values.
.Sh EXAMPLES
The following example will always return a number in
.Dv [1..99]
@@ -185,25 +230,38 @@ if (e)
.Bl -tag -width Er
.It Bq Er ECANCELED
The string did not contain any characters that were converted.
+If given
+.Fa endptr
+will be set to
+.Fa nptr .
.It Bq Er EINVAL
The
.Ar base
-is not between 2 and 36 and does not contain the special value 0.
+is not between 2 and 36 and nor is it the special value 0.
+If given
+.Fa endptr
+will be set to
+.Fa nptr .
.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 given string was out of range; the value converted has been clamped;
-or the range given was invalid, i.e.
-.Fa lo
->
-.Fa hi .
+The given string was out of range; the value converted has been clamped.
+In this case,
+.Fa endptr
+points to the terminating
+.Sq \e0
+if the
+.Fa nptr
+string was fully converted, or to the first unconverted character otherwise.
.El
.Pp
+The validity of the provided base is checked first, and if that
+fails, no further processing is attempted.
The range check is more important than the unconverted characters check,
-and it is performed first.
+and is given priority.
If a program needs to know if there were unconverted characters when an
out of range number has been provided, it needs to supply and test
.Fa endptr.
@@ -213,17 +271,19 @@ out of range number has been provided, i
.Xr atol 3 ,
.Xr atoll 3 ,
.Xr strtod 3 ,
+.Xr strtou 3 ,
.Xr strtoimax 3 ,
.Xr strtol 3 ,
.Xr strtoll 3 ,
-.Xr strtou 3 ,
.Xr strtoul 3 ,
.Xr strtoull 3 ,
-.Xr strtoumax 3
+.Xr warnc 3
.Sh STANDARDS
The
.Fn strtoi
-function is a
+and
+.Fn strtoi_l
+functions are a
.Nx
extension.
.Sh HISTORY
@@ -234,7 +294,8 @@ function first appeared in
.Ox
introduced the
.Fn strtonum 3
-function for the same purpose, but the interface makes it impossible to
-properly differentiate illegal returns.
+function for the same purpose, but its interface makes it impossible to
+properly differentiate error conditions.
.Sh BUGS
-Ignores the current locale.
+Ignores the current locale while doing the numeric conversion, only
+ASCII letters and digits are allowed, and no grouping characters.
