[Bug libc/29753] New: atoi() is documented to return 0 on error, but return -1 if outside the range of long

[Bug libc/29753] New: atoi() is documented to return 0 on error, but return -1 if outside the range of long

[thomas at habets dot se]

https://sourceware.org/bugzilla/show_bug.cgi?id=29753

            Bug ID: 29753
           Summary: atoi() is documented to return 0 on error, but return
                    -1 if outside the range of long
           Product: glibc
           Version: unspecified
            Status: UNCONFIRMED
          Severity: minor
          Priority: P2
         Component: libc
          Assignee: unassigned at sourceware dot org
          Reporter: thomas at habets dot se
                CC: drepper.fsp at gmail dot com
  Target Milestone: ---

The manpage is clear enough:

```
RETURN VALUE
       The converted value or 0 on error.
[…]
No checks for overflow or underflow are done.
```

This is not really true. atoi() uses strtol() to convert from string to long,
and the results may be under or overflow, in which case strtol() returns
LONG_MIN and LONG_MAX, respectively.

LONG_MIN cast to `int` is 0, which lives up to the manpage just fine ("0 on
error"), assuming underflow is an error.

LONG_MAX cast to `int` is -1.


So the behavior doesn't violate POSIX. But is surprising. And arguably is
incorrectly documented. There is, in fact, a range check, but but against long,
not int. "Error" is not defined in the manpage. Is over/underflow an error?

It's kinda handled, kinda not, with the effect that over and underflow have
different return values.


For atol() range checks are fully done. The strtol() manpage documents it, per
above.


It's not clear to me what the right fix is, here. Because enough code relies on
the current (IMO in the case of atoi() broken)) behavior maybe a clarification
to the manpage is in order, to say:
1. Instead of "No checks for overflow or underflow are done" say "for atoi()
the return value in case of under/overflow is undefined".
2. For atol() document the current behavior of "for atol() and atoll()
under/overflow is returned as LONG_MIN/LONG_MAX and LLONG_MIN/LLONG_MAX,
respectively".

(2) seems safe as this is already the documented behavior of strtol().


My research/rant on the properties of parsing and casting integers:

https://blog.habets.se/2022/10/No-way-to-parse-integers-in-C.html
https://blog.habets.se/2022/11/Integer-handling-is-broken.html

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug libc/29753] atoi() is documented to return 0 on error, but return -1 if outside the range of long

[sam at gentoo dot org]

https://sourceware.org/bugzilla/show_bug.cgi?id=29753

Sam James <sam at gentoo dot org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |sam at gentoo dot org

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug libc/29753] atoi() is documented to return 0 on error, but return -1 if outside the range of long

[schwab@linux-m68k.org]

https://sourceware.org/bugzilla/show_bug.cgi?id=29753

--- Comment #1 from Andreas Schwab <schwab@linux-m68k.org> ---
This should be reported to the manpage project.  The glibc documentation has
always been saying "need not dectect overflow errors".

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug libc/29753] atoi() is documented to return 0 on error, but return -1 if outside the range of long

[thomas at habets dot se]

https://sourceware.org/bugzilla/show_bug.cgi?id=29753

--- Comment #2 from Thomas Habets <thomas at habets dot se> ---
Oh, I didn't realize that manpages were managed as a different project. Thanks.

Looks like I should go here:
https://www.kernel.org/doc/man-pages/reporting_bugs.html

So assuming that maintainers here think that the behavior should not be
changed, I guess this bug can be closed?

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug libc/29753] atoi() is documented to return 0 on error, but return -1 if outside the range of long

[sam at gentoo dot org]

https://sourceware.org/bugzilla/show_bug.cgi?id=29753

--- Comment #3 from Sam James <sam at gentoo dot org> ---
For discoverability purposes, could you link to the man-pages report you make
in this bug, and vice-versa? Thanks.

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug libc/29753] atoi() is documented to return 0 on error, but return -1 if outside the range of long

[schwab@linux-m68k.org]

https://sourceware.org/bugzilla/show_bug.cgi?id=29753

Andreas Schwab <schwab@linux-m68k.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Resolution|---                         |MOVED
             Status|UNCONFIRMED                 |RESOLVED

--- Comment #4 from Andreas Schwab <schwab@linux-m68k.org> ---
Moved to man-pages bug tracker.

-- 
You are receiving this mail because:
You are on the CC list for the bug.