svn commit: r352846 - head/lib/libc/sys

[Bruce Evans]

On Sun, 29 Sep 2019, Konstantin Belousov wrote:

> On Sat, Sep 28, 2019 at 05:15:48PM +0000, Warner Losh wrote:
>> Author: imp
>> Date: Sat Sep 28 17:15:48 2019
>> New Revision: 352846
>> URL: https://svnweb.freebsd.org/changeset/base/352846
>>
>> Log:
>>   Revert the mode_t -> int changes and add a warning in the BUGS section instead.
>>
>>   While FreeBSD's implementation of these expect an int inside of libc, that's an
>>   implementation detail that we can hide from the user as it's the natural
>>   promotion of the current mode_t type and before it is used in the kernel, it's
>>   converted back to the narrower type that's the current definition of mode_t. As
>>   such, documenting int is at best confusing and at worst misleading. Instead add
>>   a note that these args are variadic and as such calling conventions may differ
>>   from non-variadic arguments.
>>
>> Modified:
>>   head/lib/libc/sys/mq_open.2
>>   head/lib/libc/sys/open.2
>>
>> Modified: head/lib/libc/sys/mq_open.2
>> ==============================================================================
>> --- head/lib/libc/sys/mq_open.2	Sat Sep 28 14:20:28 2019	(r352845)
>> +++ head/lib/libc/sys/mq_open.2	Sat Sep 28 17:15:48 2019	(r352846)
>> @@ -37,7 +37,7 @@
>>  .\"
>>  .\" $FreeBSD$
>>  .\"
>> -.Dd September 15, 2014
>> +.Dd September 28, 2019
>>  .Dt MQ_OPEN 2
>>  .Os
>>  .Sh NAME
>> @@ -133,7 +133,7 @@ Create a message queue.
>>  It requires two additional arguments:
>>  .Fa mode ,
>>  which is of type
>> -.Vt int ,
>> +.Vt mode_t ,
>>  and
>>  .Fa attr ,
>>  which is a pointer to an
>> @@ -317,6 +317,13 @@ This implementation places strict requirements on the
>>  it must begin with a slash
>>  .Pq Ql /
>>  and contain no other slash characters.
>> +.Pp
>> +The
>> +.Fa mode
>> +and
>> +.Fa attr
>> +arguments are variadic and may result in different calling conventions
>> +than might otherwise be expected.
>>  .Sh COPYRIGHT
>>  Portions of this text are reprinted and reproduced in electronic form
>>  from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
>>
>> Modified: head/lib/libc/sys/open.2
>> ==============================================================================
>> --- head/lib/libc/sys/open.2	Sat Sep 28 14:20:28 2019	(r352845)
>> +++ head/lib/libc/sys/open.2	Sat Sep 28 17:15:48 2019	(r352846)
>> @@ -28,7 +28,7 @@
>>  .\"     @(#)open.2	8.2 (Berkeley) 11/16/93
>>  .\" $FreeBSD$
>>  .\"
>> -.Dd September 17, 2019
>> +.Dd September 28, 2019
>>  .Dt OPEN 2
>>  .Os
>>  .Sh NAME
>> @@ -61,7 +61,7 @@ In this case
>>  and
>>  .Fn openat
>>  require an additional argument
>> -.Fa "int mode" ,
>> +.Fa "mode_t mode" ,
>>  and the file is created with mode
>>  .Fa mode
>>  as described in
>> @@ -615,3 +615,8 @@ permits searches.
>>  The present implementation of the
>>  .Fa openat
>>  checks the current permissions of directory instead.
>> +.Pp
>> +The
>> +.Fa mode
>> +argument is variadic and may result in different calling conventions
>> +than might otherwise be expected.
> This note is also very confusing.
>
> Assume that somebody knows calling conventions and then see this note.
> Now she would be equally misdirected because it is completely not clear
> what different conventions are mentioned there, esp. because there are no.
>
> Also, as I noted before, this note in whatever form does not belongs to
> BUSS section.

I was going to say "Indeed.  The man page already gives the type mode_t
for the mode, so the fix should be to remind the reader that since open()
is variadic, the caller MUST supply an arg whose type is the default
promotion of mode_t [and this is most easily done by starting with or
casting to an arg whose type is precisely mode_t].

POSIX gets this wronger.  It says "the file mode shall be set to the
value of the argument following the oflag argument taken as type
mode_t".  It never defines the actual type of this arg.  Since open()
is variadic, the actual type is the default promotion of whatever the
caller passes.  Nothing forbids the caller passing a long long or even
a long double, or even any type with any encoding.  Literally, this
requires the implementation to "take" the arg as a mode_t using an
unspecified conversion method after using magic beyond va_arg() to
determine the type and value of the arg.  POSIX give an example where
the arg type is precisely mode_t, but this is just an example of one
arg type that works.  All this was in the 2001 version of POSIX and
remains unfixed in the 2018 version.

So the man page was wrong after all.  It was not bug for bug compatible
with POSIX, since it says that the additional argument is "mode_t mode"
but POSIX allows any type that can be "taken" as a mode_t.

This shouldn't change the fix.  The BUGS section is not the place to
document bugs in POSIX.

Bruce