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

[Stefan Puiu <stefan.puiu@gmail.com>]

Hi Alex,

More 2 cents from me :).

On Sat, Sep 11, 2021 at 7:01 PM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi Michael,
>
> Here's a first patch set adding a new LIBRARY section
> to man2 and man3 pages (I started with man2).
>
> It is based on (mostly cloned from) FreeBSD's man pages,
> as I liked that section from them.
>
> It normalizes the information we had in comments in
> NOTES or SYNOPSIS or DESCRIPTION.
> Or in most pages we didn't even have it, as we assume that 'cc' already
> handles '-lc' by deafult.
>
> Patch 20/45 was removed on purpose due to a mistake.
>
> Cheers,
>
> Alex
>
>
>
>
>
> Alejandro Colomar (45):
>   _exit.2: Add LIBRARY section
>   keyctl.2: Add LIBRARY section
>   gamma.3: Add LIBRARY section
>   request_key.2: Add LIBRARY section
>   write.2: Add LIBRARY section
>   wait4.2: Add LIBRARY section
>   wait.2: Add LIBRARY section
>   vmsplice.2: Add LIBRARY section
>   vm86.2: Add LIBRARY section
>   vhangup.2: Add LIBRARY section
>   vfork.2: Add LIBRARY section
>   utimensat.2: Add LIBRARY section
>   utime.2: Add LIBRARY section
>   ustat.2: Add LIBRARY section
>   userfaultfd.2: Add LIBRARY section
>   unshare.2: Add LIBRARY section
>   uname.2: Add LIBRARY section
>   umount.2: Add LIBRARY section
>   tkill.2: Add LIBRARY section
>   unlink.2: Add LIBRARY section
>   umask.2: Add LIBRARY section
>   truncate.2: Add LIBRARY section
>   timer_getoverrun.2: Add LIBRARY section
>   timerfd_create.2: Add LIBRARY section
>   timer_delete.2: Add LIBRARY section
>   timer_create.2: Add LIBRARY section
>   time.2: Add LIBRARY section
>   tee.2: Add LIBRARY section
>   syslog.2: Add LIBRARY section
>   sysinfo.2: Add LIBRARY section
>   syscall.2: Add LIBRARY section
>   sync_file_range.2: Add LIBRARY section
>   sync.2: Add LIBRARY section
>   symlink.2: Add LIBRARY section
>   swapon.2: Add LIBRARY section
>   subpage_prot.2: Add LIBRARY section
>   statx.2: Add LIBRARY section
>   stat.2: Add LIBRARY section
>   spu_run.2: Add LIBRARY section
>   spu_create.2: Add LIBRARY section
>   splice.2: Add LIBRARY section
>   socketpair.2: Add LIBRARY section
>   socketcall.2: Add LIBRARY section
>   sigwaitinfo.2: Add LIBRARY section

Not sure what value "libc, -lc" to the man pages. I think having a
standardized section for functions that require libraries other than
libc is fine, so you remember when you need -lm or -lrt (although IIRC
recently a few of these were folded in libc, at least for glibc). But
-lc feels kind of redundant. Does that mean you need to add -lc in
your Makefile? Some people might interpret it as such.

I think no library section = no special library required might be clearer.

Also, on FreeBSD it's quite obvious you're talking about THE library.
But on Linux, you have glibc, musl libc, diet libc... Is the plan to
document requirements for all of these? E.g link with -lm on musl
libc, no special flags on glibc..?

Thanks,
Stefan.

>
>  man2/_exit.2            |  3 +++
>  man2/keyctl.2           |  9 +++++++--
>  man2/request_key.2      | 18 ++++--------------
>  man2/sigwaitinfo.2      |  3 +++
>  man2/socketcall.2       |  3 +++
>  man2/socketpair.2       |  3 +++
>  man2/splice.2           |  3 +++
>  man2/spu_create.2       |  3 +++
>  man2/spu_run.2          |  3 +++
>  man2/stat.2             |  3 +++
>  man2/statx.2            |  3 +++
>  man2/subpage_prot.2     |  3 +++
>  man2/swapon.2           |  3 +++
>  man2/symlink.2          |  3 +++
>  man2/sync.2             |  3 +++
>  man2/sync_file_range.2  |  3 +++
>  man2/syscall.2          |  3 +++
>  man2/sysinfo.2          |  3 +++
>  man2/syslog.2           |  3 +++
>  man2/tee.2              |  3 +++
>  man2/time.2             |  3 +++
>  man2/timer_create.2     |  5 +++--
>  man2/timer_delete.2     |  5 +++--
>  man2/timer_getoverrun.2 |  5 +++--
>  man2/timer_settime.2    |  5 +++--
>  man2/timerfd_create.2   |  3 +++
>  man2/times.2            |  3 +++
>  man2/tkill.2            |  3 +++
>  man2/truncate.2         |  3 +++
>  man2/umask.2            |  3 +++
>  man2/umount.2           |  3 +++
>  man2/uname.2            |  3 +++
>  man2/unlink.2           |  3 +++
>  man2/unshare.2          |  3 +++
>  man2/userfaultfd.2      |  3 +++
>  man2/ustat.2            |  3 +++
>  man2/utime.2            |  3 +++
>  man2/utimensat.2        |  3 +++
>  man2/vfork.2            |  3 +++
>  man2/vhangup.2          |  3 +++
>  man2/vm86.2             |  3 +++
>  man2/vmsplice.2         |  3 +++
>  man2/wait.2             |  3 +++
>  man2/wait4.2            |  3 +++
>  man2/write.2            |  3 +++
>  man3/gamma.3            |  5 +++--
>  46 files changed, 143 insertions(+), 26 deletions(-)
>
> --
> 2.33.0
>