Re: setrlimit change to prlimit change in behavior?

[Mark Wielaard <mark at klomp dot org>]

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.

> > 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.

> > > 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?

> 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?

Thanks,

Mark