Re: [PATCH RFC] Add support for linux memfd_create syscall

["Carlos O'Donell" <carlos at redhat dot com>]

On 01/14/2015 02:36 AM, Michael Kerrisk (man-pages) wrote:
>> You can disclaim your changes.
>>
>> See:
>> https://sourceware.org/glibc/wiki/Contribution%20checklist#FSF_copyright_Assignment
>>
>> The disclaimer request is here:
>> http://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/Copyright/request-disclaim.changes
> 
> Okay. I'd be okay with doing that. If you want that for the
> memfd_create() material, let me know.
> 
> But, to take the larger point a little further. For system calls such
> as memfd_create(), presumably the most that that glibc is going to do
> is supply a wrapper and a header file with some declarations and
> constants. Does the glibc project then really want to get into the
> business of maintaining documentation for another project's APIs?

Yes, and no.

If glibc has wrappers for the functions it should document them.
There should be no hidden APIs that we export publicly that aren't
listed in the manual as being APIs we support.

Exactly what gets documented can be discussed at the time of the
inclusion of the API. For example the documentation might be only
the declaration of the API, safety information, a brief discussion,
and a reference to the permanent URL for the linux man-pages project
reference (we have one of those right? ;-)).

Does that clarify my position?

The POSIX docs, C standard docs, glibc manual, and linux man pages
all serve slightly different purposes.

I agree that duplicating documentation seems like a terrible waste
of resources, but if the audience and style changes we need to
adjust our documentation.

This kind of discussion is new territory, and we need to flesh out
exactly how we're going to collaborate on this kind of thing.

> Somehow, that seems a little... odd. (Yes, I know glibc is exposing
> the APIs, but in the end, it has fairly limited control over them.)

It does have limited control over the implementation, but it has
API and ABI guarantees to uphold, and those are serious issues for
applications and part of the reason we document things i.e. to give
our users a guarantee.

Cheers,
Carlos.