Re: [PATCH] scanf.3: Do not mention the ERANGE error

Ian Abbott
2022-12-09T19:28:31Z

On 09/12/2022 18:59, Alejandro Colomar wrote:
> Hi Ian,
>
> On 12/8/22 13:34, Ian Abbott wrote:
>> The `scanf()` function does not intentionally set `errno` to `ERANGE`.
>> That is just a side effect of the code that it uses to perform
>> conversions.  It also does not work as reliably as indicated in the
>> 'man' page when the target integer type is narrower than `long`.
>> Typically (at least in glibc) for target integer types narrower than
>> `long`, the number has to exceed the range of `long` (for signed
>> conversions) or `unsigned long` (for unsigned conversions) for `errno`
>> to be set to `ERANGE`.
>>
>> Documenting `ERANGE` in the ERRORS section kind of implies that
>> `scanf()` should return `EOF` when an integer overflow is encountered,
>> which it doesn't (and doing so would violate the C standard).
>>
>> Just remove any mention of the `ERANGE` error to avoid confusion.
>>
>> Fixes: 646af540e467 ("Add an ERRORS section documenting at least some
>> of the errors that may occur for scanf().")
>> Cc: Michael Kerrisk <mtk.manpages@gmail.com>
>> Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
>
> I see.  How about saying something like "it may also fail for any of any
> errors that functions used to perform the conversions may fail"?

It depends what you mean by "fail". These errors do not make scanf
return EOF. Technically, the behavior is undefined if the result of the
conversion cannot be represented in the object being assigned to by
scanf. (In the case of glibc, that probably results in either the
integer object being set to a truncated version of the input integer, or
the integer object being set to a truncated version of LONG_MIN or
LONG_MAX, depending on the actual number.)

Setting errno to 0 before calling scanf and expecting errno to have a
meaningful value when scanf returns something other than EOF is bogus usage.

>
> Cheers,
>
> Alex

Cheers,
Ian

>
>> ---
>>   man3/scanf.3 | 7 -------
>>   1 file changed, 7 deletions(-)
>>
>> diff --git a/man3/scanf.3 b/man3/scanf.3
>> index ba470a5c1..c5ff59f45 100644
>> --- a/man3/scanf.3
>> +++ b/man3/scanf.3
>> @@ -576,10 +576,6 @@ is NULL.
>>   .TP
>>   .B ENOMEM
>>   Out of memory.
>> -.TP
>> -.B ERANGE
>> -The result of an integer conversion would exceed the size
>> -that can be stored in the corresponding integer type.
>>   .SH ATTRIBUTES
>>   For an explanation of the terms used in this section, see
>>   .BR attributes (7).
>> @@ -609,9 +605,6 @@ The functions
>>   and
>>   .BR sscanf ()
>>   conform to C89 and C99 and POSIX.1-2001.
>> -These standards do not specify the
>> -.B ERANGE
>> -error.
>>   .PP
>>   The
>>   .B q
>

--
-=( Ian Abbott <abbotti@mev.co.uk> || MEV Ltd. is a company )=-
-=( registered in England & Wales. Regd. number: 02862268. )=-
-=( Regd. addr.: S11 & 12 Building 67, Europa Business Park, )=-
-=( Bird Hall Lane, STOCKPORT, SK3 0XA, UK. || www.mev.co.uk )=-