[PATCH v1] man/man3/strtoul.3: BUGS: Signed numbers are not rejected

[PATCH v1] man/man3/strtoul.3: BUGS: Signed numbers are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1452 bytes --]

Reported-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi Bruno,

This is one of the patches I will apply after your report.  Please
review.  Thanks!


Cheers,
Alex


 man/man3/strtoul.3 | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/man/man3/strtoul.3 b/man/man3/strtoul.3
index 9eb260dae..62b9f65f6 100644
--- a/man/man3/strtoul.3
+++ b/man/man3/strtoul.3
@@ -204,11 +204,29 @@ .SH CAVEATS
 and then determine if an error occurred by checking whether
 .I errno
 has a nonzero value after the call.
-.P
-Negative values are considered valid input and are
-silently converted to the equivalent
-.I "unsigned long"
+.SH BUGS
+.SS Signed numbers
+Negative values
+are considered valid input and
+are silently converted to the equivalent
+.I unsigned long
 value.
+.P
+Users should reject signed numbers
+with a wrapper function.
+.IP
+.EX
+unsigned long
+strtoul_u(const char *restrict s, char **restrict endp, int base)
+{
+	while (isspace((unsigned char) *s))
+		s++;
+	if (!isxdigit((unsigned char) *s))
+		return 0;
+\&
+	return strtoul(s, endp, base);
+}
+.EE
 .SH EXAMPLES
 See the example on the
 .BR strtol (3)

Range-diff against v0:
-:  --------- > 1:  939641570 man/man3/strtoul.3: BUGS: Signed numbers are not rejected

base-commit: e921861a3d30cfc5f9263747a4e64a68e488288c
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1] man/man3/strtoul.3: BUGS: Signed numbers are not rejected

[Bruno Haible]

Alejandro Colomar wrote:
> This is one of the patches I will apply after your report.  Please
> review.

Looks good to me, except for one line in the sample:

> +	if (!isxdigit((unsigned char) *s))

For a general base, this should be

          if (!isalnum((unsigned char) *s))

For base <= 16, it can be simplified to

          if (!isxdigit((unsigned char) *s))

For base <= 10, it can be simplified to

          if (!isdigit((unsigned char) *s))

Bruno

[PATCH v2 0/2] strto[u]l(3) BUGS and CAVEATS

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2926 bytes --]

Hi Bruno,

This time, I've added a mention to white space.  I've decided to put
both bugs in the same commit.

And I've added a commit clarifying how to do range checks correctly.


Have a lovely night!
Alex

Alejandro Colomar (2):
  man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not
    rejected
  man/man3/strtol.3: CAVEATS: Clarify how to perform range checks

 man/man3/strtol.3  | 20 ++++++++++++++++++++
 man/man3/strtoul.3 | 19 ++++++++++++++-----
 2 files changed, 34 insertions(+), 5 deletions(-)

Range-diff against v1:
1:  939641570 ! 1:  8faa6a809 man/man3/strtoul.3: BUGS: Signed numbers are not rejected
    @@ Metadata
     Author: Alejandro Colomar <alx@kernel.org>
     
      ## Commit message ##
    -    man/man3/strtoul.3: BUGS: Signed numbers are not rejected
    +    man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected
     
         Reported-by: Bruno Haible <bruno@clisp.org>
         Signed-off-by: Alejandro Colomar <alx@kernel.org>
     
    + ## man/man3/strtol.3 ##
    +@@ man/man3/strtol.3: .SH CAVEATS
    +     goto unsupported_base;
    + .EE
    + .in
    ++.SH BUGS
    ++.SS White space
    ++These functions silently accept leading white space.
    ++One should call
    ++.BR isspace (3)
    ++before
    ++.BR strtol ()
    ++to reject white space.
    + .SH EXAMPLES
    + The program shown below demonstrates the use of
    + .BR strtol ().
    +
      ## man/man3/strtoul.3 ##
     @@ man/man3/strtoul.3: .SH CAVEATS
      and then determine if an error occurred by checking whether
    @@ man/man3/strtoul.3: .SH CAVEATS
     -Negative values are considered valid input and are
     -silently converted to the equivalent
     -.I "unsigned long"
    +-value.
     +.SH BUGS
     +.SS Signed numbers
     +Negative values
     +are considered valid input and
    -+are silently converted to the equivalent
    -+.I unsigned long
    - value.
    -+.P
    -+Users should reject signed numbers
    -+with a wrapper function.
    -+.IP
    -+.EX
    -+unsigned long
    -+strtoul_u(const char *restrict s, char **restrict endp, int base)
    -+{
    -+	while (isspace((unsigned char) *s))
    -+		s++;
    -+	if (!isxdigit((unsigned char) *s))
    -+		return 0;
    -+\&
    -+	return strtoul(s, endp, base);
    -+}
    -+.EE
    ++are silently converted to
    ++.IR "\%unsigned\ long" .
    ++.SS White space
    ++These functions silently accept leading whitespace.
    ++.SS isxdigit(3)
    ++One should call
    ++.BR isxdigit (3)
    ++before
    ++.BR strtoul ()
    ++to reject white space and/or a sign.
      .SH EXAMPLES
      See the example on the
      .BR strtol (3)
-:  --------- > 2:  b5244e62c man/man3/strtol.3: CAVEATS: Clarify how to perform range checks

base-commit: e921861a3d30cfc5f9263747a4e64a68e488288c
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1516 bytes --]

Reported-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/strtol.3  |  8 ++++++++
 man/man3/strtoul.3 | 19 ++++++++++++++-----
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/man/man3/strtol.3 b/man/man3/strtol.3
index 9323873a9..03047f10a 100644
--- a/man/man3/strtol.3
+++ b/man/man3/strtol.3
@@ -224,6 +224,14 @@ .SH CAVEATS
     goto unsupported_base;
 .EE
 .in
+.SH BUGS
+.SS White space
+These functions silently accept leading white space.
+One should call
+.BR isspace (3)
+before
+.BR strtol ()
+to reject white space.
 .SH EXAMPLES
 The program shown below demonstrates the use of
 .BR strtol ().
diff --git a/man/man3/strtoul.3 b/man/man3/strtoul.3
index 9eb260dae..1832f9d73 100644
--- a/man/man3/strtoul.3
+++ b/man/man3/strtoul.3
@@ -204,11 +204,20 @@ .SH CAVEATS
 and then determine if an error occurred by checking whether
 .I errno
 has a nonzero value after the call.
-.P
-Negative values are considered valid input and are
-silently converted to the equivalent
-.I "unsigned long"
-value.
+.SH BUGS
+.SS Signed numbers
+Negative values
+are considered valid input and
+are silently converted to
+.IR "\%unsigned\ long" .
+.SS White space
+These functions silently accept leading whitespace.
+.SS isxdigit(3)
+One should call
+.BR isxdigit (3)
+before
+.BR strtoul ()
+to reject white space and/or a sign.
 .SH EXAMPLES
 See the example on the
 .BR strtol (3)
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 2/2] man/man3/strtol.3: CAVEATS: Clarify how to perform range checks

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 815 bytes --]

Reported-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/strtol.3 | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/man/man3/strtol.3 b/man/man3/strtol.3
index 03047f10a..973d6a78b 100644
--- a/man/man3/strtol.3
+++ b/man/man3/strtol.3
@@ -192,6 +192,7 @@ .SH HISTORY
 .BR strtoll ()
 POSIX.1-2001, C99.
 .SH CAVEATS
+.SS Range checks
 Since
 .BR strtol ()
 can legitimately return 0,
@@ -210,6 +211,17 @@ .SH CAVEATS
 .I errno == ERANGE
 after the call.
 .P
+.in +4n
+.EX
+errno = 0;
+n = strtol(s, NULL, base)
+if ((errno == ERANGE && n == min) || n < min)
+	goto too_low;
+if ((errno == ERANGE && n == max) || n > max)
+	goto too_high;
+.EE
+.in
+.SS base
 If the
 .I base
 needs to be tested,
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1] man/man3/strtoul.3: BUGS: Signed numbers are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 801 bytes --]

Hi,

On Fri, Mar 21, 2025 at 10:31:39PM +0100, Bruno Haible wrote:
> Alejandro Colomar wrote:
> > This is one of the patches I will apply after your report.  Please
> > review.
> 
> Looks good to me, except for one line in the sample:
> 
> > +	if (!isxdigit((unsigned char) *s))
> 
> For a general base, this should be
> 
>           if (!isalnum((unsigned char) *s))

Hmmm, thanks!  I fogot about base 29.  :)
I'll take that for v3.

> 
> For base <= 16, it can be simplified to
> 
>           if (!isxdigit((unsigned char) *s))
> 
> For base <= 10, it can be simplified to
> 
>           if (!isdigit((unsigned char) *s))

Yep, although I won't mention that.  Since isalnum(3) works for all,
I'll say that.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v3 0/2] strto[u]l.3: BUGS and CAVEATS

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1847 bytes --]

Hi!

Here's v3, suggesting alnum(3) instead of isxdigit(3), and also making
the wording slightly more precise, since not all negative numbers are
accepted; only some (I don't feel like explaining it with details; it's
easier to just say it's a bug to be workarounded).  Add a link.


Cheers,
Alex

Alejandro Colomar (2):
  man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not
    rejected
  man/man3/strtol.3: CAVEATS: Clarify how to perform range checks

 man/man3/strtol.3  | 20 ++++++++++++++++++++
 man/man3/strtoul.3 | 19 ++++++++++++++-----
 2 files changed, 34 insertions(+), 5 deletions(-)

Range-diff against v2:
1:  8faa6a809 ! 1:  3c456a1a0 man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected
    @@ Metadata
      ## Commit message ##
         man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected
     
    +    Link: <https://stackoverflow.com/questions/60955490/strtoul-what-is-the-correct-return-value-for-very-negative-strings>
         Reported-by: Bruno Haible <bruno@clisp.org>
         Signed-off-by: Alejandro Colomar <alx@kernel.org>
     
    @@ man/man3/strtoul.3: .SH CAVEATS
     -value.
     +.SH BUGS
     +.SS Signed numbers
    -+Negative values
    ++Some negative values
     +are considered valid input and
     +are silently converted to
     +.IR "\%unsigned\ long" .
     +.SS White space
     +These functions silently accept leading whitespace.
    -+.SS isxdigit(3)
    ++.SS isalnum(3)
     +One should call
    -+.BR isxdigit (3)
    ++.BR isalnum (3)
     +before
     +.BR strtoul ()
     +to reject white space and/or a sign.
2:  b5244e62c = 2:  020b468a3 man/man3/strtol.3: CAVEATS: Clarify how to perform range checks

base-commit: e921861a3d30cfc5f9263747a4e64a68e488288c
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v3 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1640 bytes --]

Link: <https://stackoverflow.com/questions/60955490/strtoul-what-is-the-correct-return-value-for-very-negative-strings>
Reported-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/strtol.3  |  8 ++++++++
 man/man3/strtoul.3 | 19 ++++++++++++++-----
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/man/man3/strtol.3 b/man/man3/strtol.3
index 9323873a9..03047f10a 100644
--- a/man/man3/strtol.3
+++ b/man/man3/strtol.3
@@ -224,6 +224,14 @@ .SH CAVEATS
     goto unsupported_base;
 .EE
 .in
+.SH BUGS
+.SS White space
+These functions silently accept leading white space.
+One should call
+.BR isspace (3)
+before
+.BR strtol ()
+to reject white space.
 .SH EXAMPLES
 The program shown below demonstrates the use of
 .BR strtol ().
diff --git a/man/man3/strtoul.3 b/man/man3/strtoul.3
index 9eb260dae..9e73190f5 100644
--- a/man/man3/strtoul.3
+++ b/man/man3/strtoul.3
@@ -204,11 +204,20 @@ .SH CAVEATS
 and then determine if an error occurred by checking whether
 .I errno
 has a nonzero value after the call.
-.P
-Negative values are considered valid input and are
-silently converted to the equivalent
-.I "unsigned long"
-value.
+.SH BUGS
+.SS Signed numbers
+Some negative values
+are considered valid input and
+are silently converted to
+.IR "\%unsigned\ long" .
+.SS White space
+These functions silently accept leading whitespace.
+.SS isalnum(3)
+One should call
+.BR isalnum (3)
+before
+.BR strtoul ()
+to reject white space and/or a sign.
 .SH EXAMPLES
 See the example on the
 .BR strtol (3)
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v3 2/2] man/man3/strtol.3: CAVEATS: Clarify how to perform range checks

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 815 bytes --]

Reported-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/strtol.3 | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/man/man3/strtol.3 b/man/man3/strtol.3
index 03047f10a..973d6a78b 100644
--- a/man/man3/strtol.3
+++ b/man/man3/strtol.3
@@ -192,6 +192,7 @@ .SH HISTORY
 .BR strtoll ()
 POSIX.1-2001, C99.
 .SH CAVEATS
+.SS Range checks
 Since
 .BR strtol ()
 can legitimately return 0,
@@ -210,6 +211,17 @@ .SH CAVEATS
 .I errno == ERANGE
 after the call.
 .P
+.in +4n
+.EX
+errno = 0;
+n = strtol(s, NULL, base)
+if ((errno == ERANGE && n == min) || n < min)
+	goto too_low;
+if ((errno == ERANGE && n == max) || n > max)
+	goto too_high;
+.EE
+.in
+.SS base
 If the
 .I base
 needs to be tested,
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Bruno Haible]

Thanks for theses BUGS sections, Alejandro.

> +.SS White space
> +These functions silently accept leading white space.
> +One should call
> +.BR isspace (3)
> +before
> +.BR strtol ()
> +to reject white space.

Just a question of wording, but it would be more straightforward to read
when written like this:

+.SS White space
+These functions silently accept leading white space.
+In situations where rejecting white space is desired instead, call
+.BR isspace (3)
+before
+.BR strtol ().

(As usual, presenting the "why" and "what" before the "how" is nicer. [1])

> +One should call
> +.BR isalnum (3)
> +before
> +.BR strtoul ()
> +to reject white space and/or a sign.

Likewise here. It is more straightforward when written like this:

+To reject white space and/or a sign, call
+.BR isalnum (3)
+before
+.BR strtoul ().

Bruno

[1] https://gitlab.com/ghwiki/gnow-how/-/wikis/Documentation/Writing

Re: [PATCH v3 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1474 bytes --]

Hi Bruno,

On Sun, Mar 23, 2025 at 11:27:53AM +0100, Bruno Haible wrote:
> Thanks for theses BUGS sections, Alejandro.
> 
> > +.SS White space
> > +These functions silently accept leading white space.
> > +One should call
> > +.BR isspace (3)
> > +before
> > +.BR strtol ()
> > +to reject white space.
> 
> Just a question of wording, but it would be more straightforward to read
> when written like this:
> 
> +.SS White space
> +These functions silently accept leading white space.
> +In situations where rejecting white space is desired instead, call
> +.BR isspace (3)
> +before
> +.BR strtol ().
> 
> (As usual, presenting the "why" and "what" before the "how" is nicer. [1])

LGTM.  I'd make it shorter, though.  How about this?

+.SS White space
+These functions silently accept leading white space.
+To reject white space, call
+.BR isspace (3)
+before
+.BR strtol ().

which BTW makes it more consistent with your proposal from below.

> 
> > +One should call
> > +.BR isalnum (3)
> > +before
> > +.BR strtoul ()
> > +to reject white space and/or a sign.
> 
> Likewise here. It is more straightforward when written like this:
> 
> +To reject white space and/or a sign, call
> +.BR isalnum (3)
> +before
> +.BR strtoul ().
> 
> Bruno
> 
> [1] https://gitlab.com/ghwiki/gnow-how/-/wikis/Documentation/Writing

Thanks!  That's useful.  :)


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v4 0/2] strto[u]l.3: BUGS and CAVEATS

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1910 bytes --]

Hi!

Here's v4, with minor wording fixes.  Bruno, I've added you as
Co-authored-by in patch 1/2.  Please sign the patch if you like it.


Cheers,
Alex

Alejandro Colomar (2):
  man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not
    rejected
  man/man3/strtol.3: CAVEATS: Clarify how to perform range checks

 man/man3/strtol.3  | 19 +++++++++++++++++++
 man/man3/strtoul.3 | 18 +++++++++++++-----
 2 files changed, 32 insertions(+), 5 deletions(-)

Range-diff against v3:
1:  3c456a1a0 ! 1:  4a1de398d man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected
    @@ Commit message
     
         Link: <https://stackoverflow.com/questions/60955490/strtoul-what-is-the-correct-return-value-for-very-negative-strings>
         Reported-by: Bruno Haible <bruno@clisp.org>
    +    Co-authored-by: Bruno Haible <bruno@clisp.org>
         Signed-off-by: Alejandro Colomar <alx@kernel.org>
     
      ## man/man3/strtol.3 ##
    @@ man/man3/strtol.3: .SH CAVEATS
     +.SH BUGS
     +.SS White space
     +These functions silently accept leading white space.
    -+One should call
    ++To reject white space, call
     +.BR isspace (3)
     +before
    -+.BR strtol ()
    -+to reject white space.
    ++.BR strtol ().
      .SH EXAMPLES
      The program shown below demonstrates the use of
      .BR strtol ().
    @@ man/man3/strtoul.3: .SH CAVEATS
     +.SS White space
     +These functions silently accept leading whitespace.
     +.SS isalnum(3)
    -+One should call
    ++To reject white space and/or a sign, call
     +.BR isalnum (3)
     +before
    -+.BR strtoul ()
    -+to reject white space and/or a sign.
    ++.BR strtoul ().
      .SH EXAMPLES
      See the example on the
      .BR strtol (3)
2:  020b468a3 = 2:  98af3aa6c man/man3/strtol.3: CAVEATS: Clarify how to perform range checks
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1662 bytes --]

Link: <https://stackoverflow.com/questions/60955490/strtoul-what-is-the-correct-return-value-for-very-negative-strings>
Reported-by: Bruno Haible <bruno@clisp.org>
Co-authored-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/strtol.3  |  7 +++++++
 man/man3/strtoul.3 | 18 +++++++++++++-----
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/man/man3/strtol.3 b/man/man3/strtol.3
index 9323873a9..f9c9af4bc 100644
--- a/man/man3/strtol.3
+++ b/man/man3/strtol.3
@@ -224,6 +224,13 @@ .SH CAVEATS
     goto unsupported_base;
 .EE
 .in
+.SH BUGS
+.SS White space
+These functions silently accept leading white space.
+To reject white space, call
+.BR isspace (3)
+before
+.BR strtol ().
 .SH EXAMPLES
 The program shown below demonstrates the use of
 .BR strtol ().
diff --git a/man/man3/strtoul.3 b/man/man3/strtoul.3
index 9eb260dae..c4f8961a4 100644
--- a/man/man3/strtoul.3
+++ b/man/man3/strtoul.3
@@ -204,11 +204,19 @@ .SH CAVEATS
 and then determine if an error occurred by checking whether
 .I errno
 has a nonzero value after the call.
-.P
-Negative values are considered valid input and are
-silently converted to the equivalent
-.I "unsigned long"
-value.
+.SH BUGS
+.SS Signed numbers
+Some negative values
+are considered valid input and
+are silently converted to
+.IR "\%unsigned\ long" .
+.SS White space
+These functions silently accept leading whitespace.
+.SS isalnum(3)
+To reject white space and/or a sign, call
+.BR isalnum (3)
+before
+.BR strtoul ().
 .SH EXAMPLES
 See the example on the
 .BR strtol (3)
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v4 2/2] man/man3/strtol.3: CAVEATS: Clarify how to perform range checks

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 815 bytes --]

Reported-by: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/strtol.3 | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/man/man3/strtol.3 b/man/man3/strtol.3
index f9c9af4bc..f1c5b6ec1 100644
--- a/man/man3/strtol.3
+++ b/man/man3/strtol.3
@@ -192,6 +192,7 @@ .SH HISTORY
 .BR strtoll ()
 POSIX.1-2001, C99.
 .SH CAVEATS
+.SS Range checks
 Since
 .BR strtol ()
 can legitimately return 0,
@@ -210,6 +211,17 @@ .SH CAVEATS
 .I errno == ERANGE
 after the call.
 .P
+.in +4n
+.EX
+errno = 0;
+n = strtol(s, NULL, base)
+if ((errno == ERANGE && n == min) || n < min)
+	goto too_low;
+if ((errno == ERANGE && n == max) || n > max)
+	goto too_high;
+.EE
+.in
+.SS base
 If the
 .I base
 needs to be tested,
-- 
2.47.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Bruno Haible]

Looks all good to me.

Signed-off-by: Bruno Haible <bruno@clisp.org>

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 435 bytes --]

Hi Bruno,

On Sun, Mar 23, 2025 at 02:20:28PM +0100, Bruno Haible wrote:
> Looks all good to me.
> 
> Signed-off-by: Bruno Haible <bruno@clisp.org>

Thanks!  I've applied this patch:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=cbcf76d19f864da8c54e41b600ff5661b195b58e>

Is patch 2/2 also good to you?


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Bruno Haible]

Alejandro Colomar wrote:
> Is patch 2/2 also good to you?

I couldn't tell without looking at the entire page
("groff -Tutf8 -mandoc strtol.3 | less -R"). But now...

> <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=cbcf76d19f864da8c54e41b600ff5661b195b58e>

you gave me the information where to look at your work-in-progress tree.

Here are my findings on these two pages:

* In strtol.3, the example has three mistakes:
  - Missing semicolon at the end of the second line.
  - If LONG_MIN < min < LONG_MAX, the condition (errno == ERANGE && n == min)
    will never be true.
    If LONG_MIN < max < LONG_MAX, the condition (errno == ERANGE && n == max)
    will never be true.
  - It does not distinguish success with value 0 from failure due to
    no digits. (This matters when min <= 0 <= max.) Since errno is not
    guaranteed to be set in this case, the caller needs to look at *endptr.
    The example thus becomes:

           char *end;
           errno = 0;
           n = strtol(s, &end, base);
           if (end == s)
                goto no_number;
           if ((errno == ERANGE && n == LONG_MIN) || n < min)
                goto too_low;
           if ((errno == ERANGE && n == LONG_MAX) || n > max)
                goto too_high;

* strtol.3 and strtoul.3 mention
  "If base is zero or 16, the string may then include a "0x" or "0X" prefix,
   and the number will be read in base 16"
  They should also mention:
  "If base is zero or 2, the string may then include a "0b" or "0B" prefix,
   and the number will be read in base 2"
  References:
  - ISO C 23 § 7.24.1.7.(3)
  - https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=64924422a99690d147a166b4de3103f3bf3eaf6c

Bruno

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2691 bytes --]

Hi Bruno,

On Sun, Mar 23, 2025 at 04:52:15PM +0100, Bruno Haible wrote:
> Alejandro Colomar wrote:
> > Is patch 2/2 also good to you?
> 
> I couldn't tell without looking at the entire page
> ("groff -Tutf8 -mandoc strtol.3 | less -R"). But now...
> 
> > <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=cbcf76d19f864da8c54e41b600ff5661b195b58e>
> 
> you gave me the information where to look at your work-in-progress tree.

Yup.  :)

> Here are my findings on these two pages:
> 
> * In strtol.3, the example has three mistakes:
>   - Missing semicolon at the end of the second line.

Thanks!

>   - If LONG_MIN < min < LONG_MAX, the condition (errno == ERANGE && n == min)
>     will never be true.
>     If LONG_MIN < max < LONG_MAX, the condition (errno == ERANGE && n == max)
>     will never be true.

D'oh!  I'm too used to strtoi(3bsd) that I make these mistakes when
switching to strtol(3).

>   - It does not distinguish success with value 0 from failure due to
>     no digits. (This matters when min <= 0 <= max.) Since errno is not
>     guaranteed to be set in this case, the caller needs to look at *endptr.
>     The example thus becomes:

Yeah, I wanted to isolate the range checking from the rest.  Maybe I
should just put this in that sample code?:

         if ((errno == ERANGE && n == LONG_MIN) || n < min)
              goto too_low;
         if ((errno == ERANGE && n == LONG_MAX) || n > max)
              goto too_high;

Without having the strtol(3) call at all?

> 
>            char *end;
>            errno = 0;
>            n = strtol(s, &end, base);
>            if (end == s)
>                 goto no_number;
>            if ((errno == ERANGE && n == LONG_MIN) || n < min)
>                 goto too_low;
>            if ((errno == ERANGE && n == LONG_MAX) || n > max)
>                 goto too_high;

On the other hand, I should put this in the EXAMPLES section, to have
a full example.

> 
> * strtol.3 and strtoul.3 mention
>   "If base is zero or 16, the string may then include a "0x" or "0X" prefix,
>    and the number will be read in base 16"
>   They should also mention:
>   "If base is zero or 2, the string may then include a "0b" or "0B" prefix,
>    and the number will be read in base 2"

Yep, I need to update many pages for C23.  I'll do this update for this
page now.

Thanks!


Cheers,
Alex

>   References:
>   - ISO C 23 § 7.24.1.7.(3)
>   - https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=64924422a99690d147a166b4de3103f3bf3eaf6c
> 
> Bruno
> 
> 
> 
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3158 bytes --]

On Sun, Mar 23, 2025 at 05:55:50PM +0100, Alejandro Colomar wrote:
> Hi Bruno,
> 
> On Sun, Mar 23, 2025 at 04:52:15PM +0100, Bruno Haible wrote:
> > Alejandro Colomar wrote:
> > > Is patch 2/2 also good to you?
> > 
> > I couldn't tell without looking at the entire page
> > ("groff -Tutf8 -mandoc strtol.3 | less -R"). But now...
> > 
> > > <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=cbcf76d19f864da8c54e41b600ff5661b195b58e>
> > 
> > you gave me the information where to look at your work-in-progress tree.
> 
> Yup.  :)
> 
> > Here are my findings on these two pages:
> > 
> > * In strtol.3, the example has three mistakes:
> >   - Missing semicolon at the end of the second line.
> 
> Thanks!
> 
> >   - If LONG_MIN < min < LONG_MAX, the condition (errno == ERANGE && n == min)
> >     will never be true.
> >     If LONG_MIN < max < LONG_MAX, the condition (errno == ERANGE && n == max)
> >     will never be true.
> 
> D'oh!  I'm too used to strtoi(3bsd) that I make these mistakes when
> switching to strtol(3).
> 
> >   - It does not distinguish success with value 0 from failure due to
> >     no digits. (This matters when min <= 0 <= max.) Since errno is not
> >     guaranteed to be set in this case, the caller needs to look at *endptr.
> >     The example thus becomes:
> 
> Yeah, I wanted to isolate the range checking from the rest.  Maybe I
> should just put this in that sample code?:
> 
>          if ((errno == ERANGE && n == LONG_MIN) || n < min)
>               goto too_low;
>          if ((errno == ERANGE && n == LONG_MAX) || n > max)
>               goto too_high;
> 
> Without having the strtol(3) call at all?
> 
> > 
> >            char *end;
> >            errno = 0;
> >            n = strtol(s, &end, base);
> >            if (end == s)
> >                 goto no_number;
> >            if ((errno == ERANGE && n == LONG_MIN) || n < min)
> >                 goto too_low;
> >            if ((errno == ERANGE && n == LONG_MAX) || n > max)
> >                 goto too_high;
> 

I ended up doing what you said:

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=ebe5a89dcd431d15c54ebc22eaa35721496fee4b>

> On the other hand, I should put this in the EXAMPLES section, to have
> a full example.
> 
> > 
> > * strtol.3 and strtoul.3 mention
> >   "If base is zero or 16, the string may then include a "0x" or "0X" prefix,
> >    and the number will be read in base 16"
> >   They should also mention:
> >   "If base is zero or 2, the string may then include a "0b" or "0B" prefix,
> >    and the number will be read in base 2"
> 
> Yep, I need to update many pages for C23.  I'll do this update for this
> page now.
> 
> Thanks!
> 
> 
> Cheers,
> Alex
> 
> >   References:
> >   - ISO C 23 § 7.24.1.7.(3)
> >   - https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=64924422a99690d147a166b4de3103f3bf3eaf6c
> > 
> > Bruno
> > 
> > 
> > 
> > 
> 
> -- 
> <https://www.alejandro-colomar.es/>



-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Bruno Haible]

Alejandro,

> I ended up doing what you said:
> 
> <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=ebe5a89dcd431d15c54ebc22eaa35721496fee4b>

+if ((errno == ERANGE && n == LONG_MIN) || n > max)

Here: LONG_MIN -> LONG_MAX

Signed-off-by: Bruno Haible <bruno@clisp.org>

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 502 bytes --]

On Sun, Mar 23, 2025 at 06:11:39PM +0100, Bruno Haible wrote:
> Alejandro,
> 
> > I ended up doing what you said:
> > 
> > <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=ebe5a89dcd431d15c54ebc22eaa35721496fee4b>
> 
> +if ((errno == ERANGE && n == LONG_MIN) || n > max)
> 
> Here: LONG_MIN -> LONG_MAX
> 
> Signed-off-by: Bruno Haible <bruno@clisp.org>

Thanks!  Ameded and pushed.

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4865 bytes --]

Hi Bruno,

On Sun, Mar 23, 2025 at 04:52:15PM +0100, Bruno Haible wrote:
> * strtol.3 and strtoul.3 mention
>   "If base is zero or 16, the string may then include a "0x" or "0X" prefix,
>    and the number will be read in base 16"
>   They should also mention:
>   "If base is zero or 2, the string may then include a "0b" or "0B" prefix,
>    and the number will be read in base 2"
>   References:
>   - ISO C 23 § 7.24.1.7.(3)
>   - https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=64924422a99690d147a166b4de3103f3bf3eaf6c

Here's the proposed fix:

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=4f35fc20ec258842b713da6b0e7d06fd59b70abe>

	alx@devuan:~/src/linux/man-pages/man-pages/contrib$ git show
	commit 4f35fc20ec258842b713da6b0e7d06fd59b70abe (HEAD -> contrib, alx/contrib)
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Sun Mar 23 19:47:33 2025 +0100

	    man/man3/strto[u]l.3: C23 added "0b" and "0B"
	    
	    Link: <https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=64924422a99690d147a166b4de3103f3bf3eaf6c>
	    Reported-by: Bruno Haible <bruno@clisp.org>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3/strtol.3 b/man/man3/strtol.3
	index 2ae48119b..9c8791b07 100644
	--- a/man/man3/strtol.3
	+++ b/man/man3/strtol.3
	@@ -53,8 +53,13 @@ .SH DESCRIPTION
	 If
	 .I base
	 is zero or 16, the string may then include a
	-"0x" or "0X" prefix, and the number will be read in base 16; otherwise, a
	-zero
	+"0x" or "0X" prefix, and the number will be read in base 16;
	+if
	+.I base
	+is zero or 2, the string may then include a
	+"0b" or "0B" prefix, and the number will be read in base 2;
	+otherwise,
	+a zero
	 .I base
	 is taken as 10 (decimal) unless the next character
	 is \[aq]0\[aq], in which case it is taken as 8 (octal).
	diff --git a/man/man3/strtoul.3 b/man/man3/strtoul.3
	index c6a2bb9be..4e85f7a30 100644
	--- a/man/man3/strtoul.3
	+++ b/man/man3/strtoul.3
	@@ -59,8 +59,13 @@ .SH DESCRIPTION
	 If
	 .I base
	 is zero or 16, the string may then include a
	-"0x" or "0X" prefix, and the number will be read in base 16; otherwise, a
	-zero
	+"0x" or "0X" prefix, and the number will be read in base 16;
	+if
	+.I base
	+is zero or 2, the string may then include a
	+"0b" or "0B" prefix, and the number will be read in base 2;
	+otherwise,
	+a zero
	 .I base
	 is taken as 10 (decimal) unless the next character
	 is \[aq]0\[aq], in which case it is taken as 8 (octal).
	@@ -182,7 +187,7 @@ .SH VERSIONS
	 or to
	 .BR strtoul ().
	 .SH STANDARDS
	-C11, POSIX.1-2008.
	+C23, POSIX.1-2008.
	 .SH HISTORY
	 .TP
	 .BR strtoul ()
	@@ -190,6 +195,10 @@ .SH HISTORY
	 .TP
	 .BR strtoull ()
	 POSIX.1-2001, C99.
	+.TP
	+"0b", "0B"
	+C23.
	+glibc 2.38.
	 .SH CAVEATS
	 Since
	 .BR strtoul ()

And here's a diff of the rendered pages:

	alx@devuan:~/src/linux/man-pages/man-pages/contrib$ diffman-git HEAD
	--- HEAD^:man/man3/strtol.3
	+++ HEAD:man/man3/strtol.3
	@@ -32,7 +32,9 @@
	      space (as determined by isspace(3)) followed by  a  single
	      optional  '+'  or  '-'  sign.   If base is zero or 16, the
	      string may then include a "0x" or  "0X"  prefix,  and  the
	-     number  will be read in base 16; otherwise, a zero base is
	+     number  will be read in base 16; if base is zero or 2, the
	+     string may then include a "0b" or  "0B"  prefix,  and  the
	+     number  will  be read in base 2; otherwise, a zero base is
	      taken as 10 (decimal) unless the next character is '0', in
	      which case it is taken as 8 (octal).
	 
	--- HEAD^:man/man3/strtoul.3
	+++ HEAD:man/man3/strtoul.3
	@@ -32,7 +32,9 @@
	      space  (as  determined by isspace(3)) followed by a single
	      optional '+' or '-' sign.  If base  is  zero  or  16,  the
	      string  may  then  include  a "0x" or "0X" prefix, and the
	-     number will be read in base 16; otherwise, a zero base  is
	+     number will be read in base 16; if base is zero or 2,  the
	+     string  may  then  include  a "0b" or "0B" prefix, and the
	+     number will be read in base 2; otherwise, a zero  base  is
	      taken as 10 (decimal) unless the next character is '0', in
	      which case it is taken as 8 (octal).
	 
	@@ -100,7 +102,7 @@
	      lent to strtoull() or to strtoul().
	 
	 STANDARDS
	-     C11, POSIX.1‐2008.
	+     C23, POSIX.1‐2008.
	 
	 HISTORY
	      strtoul()
	@@ -109,6 +111,9 @@
	      strtoull()
		     POSIX.1‐2001, C99.
	 
	+     "0b", "0B"
	+            C23.  glibc 2.38.
	+
	 CAVEATS
	      Since strtoul() can legitimately  return  0  or  ULONG_MAX
	      (ULLONG_MAX  for  strtoull()) on both success and failure,


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Bruno Haible]

Alejandro Colomar wrote:
> 	diff --git a/man/man3/strtoul.3 b/man/man3/strtoul.3
> 	index c6a2bb9be..4e85f7a30 100644
> 	--- a/man/man3/strtoul.3
> 	+++ b/man/man3/strtoul.3
> 	@@ -182,7 +187,7 @@ .SH VERSIONS
> 	 or to
> 	 .BR strtoul ().
> 	 .SH STANDARDS
> 	-C11, POSIX.1-2008.
> 	+C23, POSIX.1-2008.
> 	 .SH HISTORY
> 	 .TP
> 	 .BR strtoul ()
> 	@@ -190,6 +195,10 @@ .SH HISTORY
> 	 .TP
> 	 .BR strtoull ()
> 	 POSIX.1-2001, C99.
> 	+.TP
> 	+"0b", "0B"
> 	+C23.
> 	+glibc 2.38.
> 	 .SH CAVEATS
> 	 Since
> 	 .BR strtoul ()

These same two hunks could also be applied to strtol.3.

Bruno

Re: [PATCH v4 1/2] man/man3/strto[u]l.3: BUGS: Signed numbers and white space are not rejected

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1388 bytes --]

On Sun, Mar 23, 2025 at 08:26:02PM +0100, Bruno Haible wrote:
> Alejandro Colomar wrote:
> > 	diff --git a/man/man3/strtoul.3 b/man/man3/strtoul.3
> > 	index c6a2bb9be..4e85f7a30 100644
> > 	--- a/man/man3/strtoul.3
> > 	+++ b/man/man3/strtoul.3
> > 	@@ -182,7 +187,7 @@ .SH VERSIONS
> > 	 or to
> > 	 .BR strtoul ().
> > 	 .SH STANDARDS
> > 	-C11, POSIX.1-2008.
> > 	+C23, POSIX.1-2008.
> > 	 .SH HISTORY
> > 	 .TP
> > 	 .BR strtoul ()
> > 	@@ -190,6 +195,10 @@ .SH HISTORY
> > 	 .TP
> > 	 .BR strtoull ()
> > 	 POSIX.1-2001, C99.
> > 	+.TP
> > 	+"0b", "0B"
> > 	+C23.
> > 	+glibc 2.38.
> > 	 .SH CAVEATS
> > 	 Since
> > 	 .BR strtoul ()
> 
> These same two hunks could also be applied to strtol.3.

Yep, I had forgotten.  I've applied them a moment ago.  BTW, I also
updated the info about POSIX too:

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=2b2519c7722166dbe4313da6ec048d137ea42ba7>

	@@ -183,7 +188,7 @@ .SH VERSIONS
	 or to
	 .BR strtol ().
	 .SH STANDARDS
	-C11, POSIX.1-2008.
	+C23, POSIX.1-2024.
	 .SH HISTORY
	 .TP
	 .BR strtol ()
	@@ -191,6 +196,11 @@ .SH HISTORY
	 .TP
	 .BR strtoll ()
	 POSIX.1-2001, C99.
	+.TP
	+"0b", "0B"
	+C23.
	+glibc 2.38.
	+(Not in POSIX.)
	 .SH CAVEATS
	 .SS Range checks
	 Since


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]