Hi ALex,
On 2/13/21 9:35 PM, Alejandro Colomar (man-pages) wrote:
> On 2/13/21 7:10 PM, Michael Kerrisk (man-pages) wrote:
>> On 2/13/21 7:06 PM, Michael Kerrisk (man-pages) wrote:
>>> Hi Alex,
>>>
>>> On 2/13/21 5:40 PM, Alejandro Colomar (man-pages) wrote:
>>>> Hi Michael,
>>>>
>>>> openat2(2) is documented differently in openat2.2 and open.2 (without
>>>> and with const for its 3rd parameter, respectively). The return type is
>>>> also different.
>>>>
>>>> Do you know which one is correct? Else, I could read the source...
>>>
>>> Good spotting! The openat() page is correct. And POSIX says:
>>>
>>> int openat(int fd, const char *path, int oflag, ...);
>>
>> Ignore what I just said. I was misreading your mail.
>> I'm not sure of the answer. The source says:
>>
>> SYSCALL_DEFINE4(openat2, int, dfd, const char __user *, filename,
>> struct open_how __user *, how, size_t, usize)
>>
>> Thanks,
>>
>> Michael
>>
>
> Hi Michael,
>
> How about documenting raw kernel syscalls as 'syscall(__NR_xxx, ...);',
> instead of using a hypothetical wrapper that the user should write?
Hmmm -- that's an interesting idea!
> In those functions with glibc wrappers, I'd document both the raw
> syscall and the glibc wrapper. I mean something in the line of keyctl(2).
When you say "those functions with glibc wrappers", that means about
95% of the system calls. But I guess that's not what you mean.
The SYNOPSIS in keyctl() is is somewhat separate from (albeit
related to) the current discussion.[1]
> This would end with the thing that glibc documentation "hides" kernel
> documentation (as the manual pages (usually) only document glibc
> wrappers when they exist).
>
> It would also avoid some confusion, and would be clearer than the "glibc
> doesn't provide a wrapper..." notes (we could remove them or keep them
> for even more clarity).
I'm not 100% sure, but I think I like this idea. The advantages that
you note make sense to me.
> What do you think about it?
>
> If we do that, I'd leave it for 5.12.
Let's already try one page as an RFC patch. Maybe CC Florian (and
libc-alpha), just in case he has a comment on the idea. I think I'd
keep the "glibc doesn't provide a wrapper" notes, but maybe I'll change
my mind after seeing the RFC patch.
Thanks,
Michael
[1] I think that other topic is: syscalls that have a wrapper provided
by something other than glibc. But, even then keyctl() is anomalous,
and I think the SYNOPSIS needs fixing in any case. FOllowing ideas
in exec(3), I might be inclined to replace both existing prototypes
with just:
long keyctl(int operation, ...
/*, unsigned long arg2, unsigned long arg3,
unsigned long arg4, unsigned long arg5 */);
What do you think?
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
