Syscalls documentation and librt

[Matthew Mondor <mm_lists%pulsar-zone.net@localhost>]

It seems traditional to implement all system calls in section 2 manual
pages.  Even the syscalls used by libpthread (_lwp_*) are documented
this way (there's no reason to assume pthread will forever be the only
candidate using those syscalls, even if it is generally the case, and
it's useful for developers and code auditors).

Where this differs now seems to be for the syscalls used by librt (i.e.
kern/37427, misc/38979 and I also noticed lately that mq_* also only
have userland library (section 3) documentation).  Also, manual pages
like pset(3) and cpuset(3) fail to specify linking (it appears to also
be -lrt).  pset* also seem to actually be syscalls.

What should be done about this?  Should the section 2 manual pages also
be added even where mostly redundant?  Should some of the rt man pages
be moved to section 2?  Or should there be links so that they're in
both sections, and modified as necessary if there is missing
information relating to the syscalls?

I'm willing to help improve the documentation and as necessary write
new manual pages, but I'd first need to know what the consensus is
before submitting diffs.

Reading the followup comments of misc/38979 suggests there's no
concensus yet.  rmind closed the PR assuming I hadn't noticed section 3
documentation, yet dholland seemed to agree that the documentation
could be improved.

Thanks,
-- 
Matt