Re: Wrong documentation for open()

[Richard Earnshaw <Richard dot Earnshaw at foss dot arm dot com>]

On 10/04/15 09:09, Schwarz, Konrad wrote:
> Hi Friedrich,
> 
> just to explain why this bug exists:
> 
> AFAIK, Unix originally had a two argument open(2).  creat(2) was used to create new files.
> 
> At some point, open(2) was changed to also be able to create new files.  For this case,
> a extra third argument was required.
> 
> For the ABIs (and K&R C) on which Unix ran at that time, this did not make a difference in practice;
> code could and still can use the two argument version.
> 
> With ANSI C, it was possible to
> specify this interface in terms of variable argument lists.
> 

However, changing this in newlib now would be an ABI change on some
platforms, since the presence of a variadic function marker may change
the argument passing rules.  I'm pretty sure that for some platforms
that newlib supports this could be a blocker (though I can't off-hand
say which).

R.

> Regards
> 
> Konrad
>  
>> -----Original Message-----
>> From: newlib-owner@sourceware.org [mailto:newlib-owner@sourceware.org]
>> On Behalf Of Friedrich Lobenstock
>> Sent: Donnerstag, 9. April 2015 18:03
>> To: newlib@sourceware.org
>> Subject: Re: Wrong documentation for open()
>>
>> Hello Eric!
>>
>> Eric Blake wrote on 2015-04-09 17:38 MET:
>>>>> The documentation, eg. the online version at
>>>>> <https://sourceware.org/newlib/libc.html#index-open>, is wrong in
>>>>> regards to the implementation of open().
>>>>>
>>>>> In the documentation the signature of open() is defined as:
>>>>>     int open(const char *name, int flags, int mode)
>>> That's documented merely as a minimum implementation; it always
>> fails,
>>> so it doesn't matter whether va_args is parsed compatibly or anything
>>> else.  I see nothing wrong with that documentation being a bare
>>> minimum, [...]
>>
>> BUT there's no documentation for open() other than in the minimum
>> implementation section!
>>
>> --
>> MfG / Regards
>> Friedrich Lobenstock
>