Re: setrlimit change to prlimit change in behavior?

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

On 10/20/2017 09:42 AM, Mark Wielaard wrote:
> On Fri, 2017-10-20 at 09:10 -0700, Carlos O'Donell wrote:
>> 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.
> 
> Hmmm. That doesn't seem correct. EINVAL might be returned both if you
> interpret it as pure syscall and as glibc library call. Although If you
> meant EFAULT then it depends on whether you believe it is documenting
> the glibc functions or the system calls. I believe if you are
> documenting the system calls then the intention is that they return
> EFAULT instead of producing undefined behavior.

Sorry, my mistake, I did mean EFAULT.

>>> And if I was interested in the glibc provided prlimit function?
>>> Where should I look for documentation/specification?
>>
>> info setrlimit
> 
> That doesn't provide any documentation of the glibc provided prlimit
> function.

Again, sorry I misread your question as just asking about the general
rlimit functions like setrlimit and getrlimit.

There is no glibc documentation for prlimit, it needs to be written
by someone. I admit that glibc as a community had a bad habit of 
adding extensions without documenting them. That is a very bad habit
we are breaking. I don't think we've accepted anything without
documentation recently, and if we have, please tell me and I'll
correct that. However, historical missing documentation is something
we're working on.

>>>> 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.
> 
> OK. And in all other cases it documents the glibc function?

AFAIK yes.

>> 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.
>> [...]
>> 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.
> 
> Doesn't the glibc project document its own API? That is really what I
> am after. glibc provides a prlimit function. How was that specified,
> where is it documented? How and where should I send updates to that
> documentation?

The glibc project *does* document it's own APIs, the problem is that
historically this was not enshrined well in the community practice.
It is now. And we have a backlog of APIs to document.

You need to add a new prlimit function to:
manual/resources.texi, and post the patch to libc-alpha. I'll be
happy to review.

-- 
Cheers,
Carlos.