Re: setrlimit change to prlimit change in behavior?

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

On 10/20/2017 08:56 AM, Mark Wielaard wrote:
> On Wed, 2017-10-18 at 13:10 -0700, Carlos O'Donell wrote:
>> On 10/18/2017 12:06 PM, Mark Wielaard wrote:
>> The linux man pages are not the canonical documentation for the
>> interface.
>> I suggest sending them a patch to adjust their documentation to
>> prevent further confusion.
> 
> What would you suggest the patch say?

Remove the EINVAL error specification.

>> At this moment you *cannot* know what the linux kernel interface is
>> for setprlimit without going to the linux kernel sources, and
>> getting 
>> confirmation from core kernel developers to document that interface.
> 
> And if I was interested in the glibc provided prlimit function?
> Where should I look for documentation/specification?

info setrlimit

>>> I cannot immediately deduce from this document which errors define the
>>> contract of the linux kernel interface and which of glibc.
>>
>> The linux man pages have two kinds of documentation
>>
>> - linux kernel interface documentation (see futex for an example)
>>
>> - API documentation (see getrlimit/setrlimit, prlimit for an example)
>>
>> And it does a very good job of explaining which you are looking at.
> 
> How does it make that distinction?

"Note: There is no glibc wrapper for this system call; see NOTES."

In which case it is documenting the *raw* kernel API.

> It answers my question partly :) Yes, for my valgrind work I would like
> documentation of "pure" bare linux kernel syscalls so that we can make
> valgrind memcheck better at checking the syscall contract. But as
> "normal" GNU/Linux hacker I find the combined explanation much more
> useful. Who in their right mind is going to write anything against bare
> bones linux kernel syscalls? It is the glibc wrappers that make it a
> useful interface, so it makes sense to document them in combination
> IMHO (so I believe the section 2 man pages are much more useful than
> the section 3 man pages).

You document the API.

The problem is that the people writing and submitting changes to the
linux man pages are *not* the authors of the API, and they document
what they see experimentally.

To give you a data point. When Amazon developed their AWS APIs they
chose to *consciously* and *randomly* rotate the order of the labelled
and accepted arguments to their network APIs to catch people who were
expecting and hard coding the arguments by number instead of by label.

Here we have people experimenting, seeing some error return codes,
and assuming they belong in the contract of the API when they don't.

I *wish* I could do something to break those assumptions, bu we don't
have any mechanism to do that.

-- 
Cheers,
Carlos.