Re: [PATCH 00/45] Add LIBRARY section (based on FreeBSD manual pages)

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hi, Eugene!

On 9/12/21 12:24 AM, Eugene Syromyatnikov wrote:
> On Sat, Sep 11, 2021 at 8:40 PM Alejandro Colomar (man-pages)
> <alx.manpages@gmail.com> wrote:
>>
>> Hi Eugene,
>>
>> On 9/11/21 8:29 PM, Eugene Syromyatnikov wrote:
>>> On Sat, Sep 11, 2021 at 6:01 PM Alejandro Colomar
>>> <alx.manpages@gmail.com> wrote:
>>>> Alejandro Colomar (45):
>>>>     _exit.2: Add LIBRARY section
>>>>     keyctl.2: Add LIBRARY section
>> ...
>>>>     socketcall.2: Add LIBRARY section
>>>>     sigwaitinfo.2: Add LIBRARY section
>>>
>>> I'm not sure about these, my understanding is that the primary purpose
>>> of section 2 is syscalls, userspace-kernel interface, and not their
>>> libc wrappers.  Even intro(2) states that it is Linux-specific:
>>> “Section  2  of the manual describes the Linux system calls.  A system
>>> call is an entry point into the Linux kernel.” Tying it to libc feels
>>> like a bit of a stretch, even though it is the exceedingly common
>>> interface for invoking them.
>>>
>>
>> Thanks for pointing that out.  I had some doubts about this in the
>> beginning.  I started writing something like "Linux kernel - GNU C
>> library" meaning that it's not only a thing of glibc but also the
>> kernel.  But no one replied my RFCs... :/
> 
> Apologies on my part—I read the list only occasionally.

No need to apologize.  We're doing this for free  :)

> 
>> In the end I simplified it to Standard C library (as FreeBSD does),
> 
> The issue here is that FreeBSD has a bit of a different approach,
> where libc and kernel are parts of the whole operating systems and
> quite tied together, so there's no (assumption about) multiple libc
> implementations like in Linux (it is possible, but meaningless—libc is
> a part of OS already, after all), so calling syscalls without libc is
> much more unusual than in Linux (where it is sometimes even required,
> for example, to do weird stuff on x32, for which libc, and even its
> syscall() implementation, could stand in the way).

Yes, that was my first thought...

> 
>> because I wasn't convinced of the syntax I had used.  And also, since a
>> man page being in section 2 already implies that it is implemented in
>> the kernel, I didn't want to be repetitive, and just point what the user
>> has to link to to make a program work.
>>
>> There are some system calls that are wrapped by other libraries, such as
>> keyctl(2) by libkeyutils, and those get a different LIBRARY (you can
>> check patch 02/45).
>>
>> But if you think there's a better way to express this, please propose it.
> 
> After some thinking, I think it's okay; I re-read some “C
> library/kernel differences”, and those are clearly written with the
> assumption that the described call is invoked via its libc wrapper;
> notes about the absence of a glibc wrapper for some other syscalls
> hint at the same expectation.

but as you say, man-pages already assume use of the glibc (or other 
libraries') wrappers almost everywhere; and I think doing otherwise 
would overcomplicate it.

Thanks for reviewing my patches!!

Cheers,

Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/