[PATCH v3] getrlimit.2: old_getrlimit/ugetrlimit and RLIM_INFINITY discrepancies

[PATCH v3] getrlimit.2: old_getrlimit/ugetrlimit and RLIM_INFINITY discrepancies

[Eugene Syromyatnikov]

Historically, Linux didn't follow SUS with respect to RLIM_INFINITY
signedness; it was changed during 2.4 development cycle, but in somewhat
peculiar and arch-dependent fashion due to backward compatibility
concerns.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
---
 man2/getrlimit.2 | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/man2/getrlimit.2 b/man2/getrlimit.2
index 648fd3c..5a360d4 100644
--- a/man2/getrlimit.2
+++ b/man2/getrlimit.2
@@ -646,6 +646,37 @@ The name of the glibc wrapper function is
 .BR prlimit ();
 the underlying system call is
 .BR prlimit64 ().
+The corresponding infinity value constant is provided in
+.I <linux/resource.h>
+as
+.BR RLIM64_INFINITY.
+.PP
+Original Linux implementation used signed types for limits; that was changed
+(along with the value of the
+.B RLIM_INFINITY
+constant)
+.\" http://repo.or.cz/davej-history.git/blobdiff/129f8758d8c41e0378ace0b6e2f56bbb8a1ec694..15305d2e69c3a838bacd78962c07077d2821f255:/include/linux/resource.h
+during 2.4 development cycle, as it wasn't compatible
+with Single UNIX Specification.
+However, in order to preserve backward compatibility, the routine
+.IR sys_old_getrlimit
+has been implemented under
+.B __NR_getrlimit
+syscall slot, with infinity checks being performed against hard-coded 0x7fffffff
+value, and the routine
+.I sys_getrlimit
+has been exposed under a new name,
+.BR ugetrlimit ().
+Note that most newer architectures don't have the latter, with
+.BR getrlimit ()
+providing proper implementation.
+Also worth noting that several architectures decided not to change
+.B RLIM_INFINITY
+value: 32-bit mips and sparc (but not 64-bit variants, that switched
+to the new value of (~0UL)) retained the old 0x7fffffff value,
+and alpha retained 0x7ffffffffffffffful.
+.\" ...along with a request to call when one runs into it:
+.\" https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/alpha/include/uapi/asm/resource.h#n15
 .SH BUGS
 In older Linux kernels, the
 .B SIGXCPU
-- 
2.1.4

Re: [PATCH v3] getrlimit.2: old_getrlimit/ugetrlimit and RLIM_INFINITY discrepancies

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 5002 bytes --]

Hi, Eugene!

I thought I'd offer some style suggestions since Alex hasn't yet.

At 2021-07-29T17:44:01+0200, Eugene Syromyatnikov wrote:
> +The corresponding infinity value constant is provided in
> +.I <linux/resource.h>
> +as
> +.BR RLIM64_INFINITY.
> +.PP
> +Original Linux implementation used signed types for limits; that was changed

Grammatically, you need an article at the beginning of this sentence.
More broadly, however, what constitutes "*the* original Linux
implementation" may not be well-defined and is not as relevant to the
discussion as Linux kernels that were widely deployed.  The earliest
conveivable Linux attested, what Torvalds produced on his 80386 in 1991
("Freax") is less important than Linux 2.4.

So I would recast and use semantic newlines [see man-pages(7)]:

	Linux 2.4 and earlier used signed types for limits;
	that was changed

Alex will surely direct you to the semantic newline advice in
man-pages(7).

   Use semantic newlines
       In the source of a manual page, new sentences should be started
       on new lines, and long sentences should  split  into  lines  at
       clause  breaks  (commas,  semicolons, colons, and so on).  This
       convention, sometimes known as "semantic  newlines",  makes  it
       easier to see the effect of patches, which often operate at the
       level of individual sentences or sentence clauses.

I won't point out every instance where a semantic newline is preferred.

> +(along with the value of the
> +.B RLIM_INFINITY
> +constant)

I see there is some precedent in the Linux man-pages to call a
preprocessor symbol that is replaced with a C language literal a
"constant".  I would not employ this usage myself, since C has the
"const" type qualifier that suggests, and is is widely interpreted, as
"constant".  I think it would be helpful if we referred to as "constant"
only C objects bearing such a declaration.  Does anyone think this would
be a worthwhile shift in usage?  (The most important virtue that
constants in the sense I'm using them have over preprocessor symbols is
that the former survive the translation process into executable format,
and (if not optimized out) will appear in a symbol table, which means a
debugger can know about them.)

> +.\" http://repo.or.cz/davej-history.git/blobdiff/129f8758d8c41e0378ace0b6e2f56bbb8a1ec694..15305d2e69c3a838bacd78962c07077d2821f255:/include/linux/resource.h
> +during 2.4 development cycle, as it wasn't compatible

s/during/& the/

> +with Single UNIX Specification.

s/with/& the/

> +However, in order to preserve backward compatibility, the routine

s/routine/function/ ?

> +.IR sys_old_getrlimit
> +has been implemented under

s/has been/was/
s/under/using the/

> +.B __NR_getrlimit
> +syscall slot, with infinity checks being performed against hard-coded 0x7fffffff

s/hard-coded/a literal/

> +value, and the routine

s/the routine//
(it will be clear from context that this is another function)

> +.I sys_getrlimit
> +has been exposed under a new name,

s/has been/was/
s/exposed/made available/

> +.BR ugetrlimit ().
> +Note that most newer architectures don't have the latter, with

s/Note that most/Most/

I call this a "Kemper notectomy", after my colleague in groff
development, Dave Kemper, who has pointed out that we tend to massively
overuse the phrase "note that" in software documentation.  We write for
impatient readers.  Everything we say in a manual should be worthy of
note; if it is not, it should be deleted or moved to a place in the text
reserved for supplemental commentary (a footnote; a (sub)section entitled
"Background", "History", or "Notes"; or similar).

> +.BR getrlimit ()
> +providing proper implementation.

What's "proper" about it?  That it's unsigned, or that it's conforming?
Say so.  Again, an article is needed.

s/proper/a conforming/

> +Also worth noting that several architectures decided not to change

I'd condense this.

s/Also worth noting that/However,
/

> +.B RLIM_INFINITY
> +value: 32-bit mips and sparc (but not 64-bit variants, that switched

s/mips/MIPS/

The Linux man-pages are mostly consistent about this casing[1], and it
is normative[2].

s/sparc/SPARC/

The Linux man-pages are mostly consistent about this casing[3], and it
is normative[4].

> +to the new value of (~0UL)) retained the old 0x7fffffff value,
> +and alpha retained 0x7ffffffffffffffful.

s/alpha/Alpha/

You can probably guess what I'm going to say.  ;-)

> +.\" ...along with a request to call when one runs into it:
> +.\" https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/alpha/include/uapi/asm/resource.h#n15
>  .SH BUGS
>  In older Linux kernels, the
>  .B SIGXCPU

Thank you for your patience with my comments.  I hope they've been
helpful.

Regards,
Branden

[1] vdso(7) may be an exception.
[2] https://booksite.elsevier.com/9780124077263/downloads/historial%20perspectives/section_4.16.pdf
[3] clone(2), syscall(2), and exec(3) may be exceptions.
[4] https://sparc.org/timeline/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] getrlimit.2: old_getrlimit/ugetrlimit and RLIM_INFINITY discrepancies

[Alejandro Colomar (man-pages)]

Hi Branden,

Thanks for reviewing this!
I didn't have more time today.

Also seeing reviews from different people helps improving my reviews too :)


On 7/30/21 12:35 AM, G. Branden Robinson wrote:
> Hi, Eugene!
> 
> I thought I'd offer some style suggestions since Alex hasn't yet.
> 
> At 2021-07-29T17:44:01+0200, Eugene Syromyatnikov wrote:
>> +The corresponding infinity value constant is provided in
>> +.I <linux/resource.h>
>> +as
>> +.BR RLIM64_INFINITY.
>> +.PP
>> +Original Linux implementation used signed types for limits; that was changed
> 
> Grammatically, you need an article at the beginning of this sentence.
> More broadly, however, what constitutes "*the* original Linux
> implementation" may not be well-defined and is not as relevant to the
> discussion as Linux kernels that were widely deployed.  The earliest
> conveivable Linux attested, what Torvalds produced on his 80386 in 1991
> ("Freax") is less important than Linux 2.4.
> 
> So I would recast and use semantic newlines [see man-pages(7)]:
> 
> 	Linux 2.4 and earlier used signed types for limits;
> 	that was changed
> 
> Alex will surely direct you to the semantic newline advice in
> man-pages(7).

:-)

> 
>     Use semantic newlines
>         In the source of a manual page, new sentences should be started
>         on new lines, and long sentences should  split  into  lines  at
>         clause  breaks  (commas,  semicolons, colons, and so on).  This
>         convention, sometimes known as "semantic  newlines",  makes  it
>         easier to see the effect of patches, which often operate at the
>         level of individual sentences or sentence clauses.
> 
> I won't point out every instance where a semantic newline is preferred.
> 
>> +(along with the value of the
>> +.B RLIM_INFINITY
>> +constant)
> 
> I see there is some precedent in the Linux man-pages to call a
> preprocessor symbol that is replaced with a C language literal a
> "constant".  I would not employ this usage myself, since C has the
> "const" type qualifier that suggests, and is is widely interpreted, as
> "constant".  I think it would be helpful if we referred to as "constant"
> only C objects bearing such a declaration.  Does anyone think this would
> be a worthwhile shift in usage?  (The most important virtue that
> constants in the sense I'm using them have over preprocessor symbols is
> that the former survive the translation process into executable format,
> and (if not optimized out) will appear in a symbol table, which means a
> debugger can know about them.)

I had a look at the Standard to check what wording is used there.  It 
uses "constant" too.  You can find many cases of "decimal constant", 
"double constant", "character constant" in contexts containing also 
"string literal".  Have a special look at the "Constants" section.

https://stackoverflow.com/questions/81656/where-do-i-find-the-current-c-or-c-standard-documents

> 
>> +.\" http://repo.or.cz/davej-history.git/blobdiff/129f8758d8c41e0378ace0b6e2f56bbb8a1ec694..15305d2e69c3a838bacd78962c07077d2821f255:/include/linux/resource.h
>> +during 2.4 development cycle, as it wasn't compatible
> 
> s/during/& the/
> 
>> +with Single UNIX Specification.
> 
> s/with/& the/
> 
>> +However, in order to preserve backward compatibility, the routine
> 
> s/routine/function/ ?
> 
>> +.IR sys_old_getrlimit
>> +has been implemented under
> 
> s/has been/was/
> s/under/using the/
> 
>> +.B __NR_getrlimit
>> +syscall slot, with infinity checks being performed against hard-coded 0x7fffffff
> 
> s/hard-coded/a literal/
> 
>> +value, and the routine
> 
> s/the routine//
> (it will be clear from context that this is another function)
> 
>> +.I sys_getrlimit
>> +has been exposed under a new name,
> 
> s/has been/was/
> s/exposed/made available/
> 
>> +.BR ugetrlimit ().
>> +Note that most newer architectures don't have the latter, with
> 
> s/Note that most/Most/
> 
> I call this a "Kemper notectomy", after my colleague in groff
> development, Dave Kemper, who has pointed out that we tend to massively
> overuse the phrase "note that" in software documentation.  We write for
> impatient readers.  Everything we say in a manual should be worthy of
> note; if it is not, it should be deleted or moved to a place in the text
> reserved for supplemental commentary (a footnote; a (sub)section entitled
> "Background", "History", or "Notes"; or similar).
> 
>> +.BR getrlimit ()
>> +providing proper implementation.
> 
> What's "proper" about it?  That it's unsigned, or that it's conforming?
> Say so.  Again, an article is needed.
> 
> s/proper/a conforming/
> 
>> +Also worth noting that several architectures decided not to change
> 
> I'd condense this.
> 
> s/Also worth noting that/However,
> /
> 
>> +.B RLIM_INFINITY
>> +value: 32-bit mips and sparc (but not 64-bit variants, that switched
> 
> s/mips/MIPS/
> 
> The Linux man-pages are mostly consistent about this casing[1], and it
> is normative[2].
> 
> s/sparc/SPARC/
> 
> The Linux man-pages are mostly consistent about this casing[3], and it
> is normative[4].
> 
>> +to the new value of (~0UL)) retained the old 0x7fffffff value,
>> +and alpha retained 0x7ffffffffffffffful.
> 
> s/alpha/Alpha/
> 
> You can probably guess what I'm going to say.  ;-)

Thanks for this.  I had doubts about how to write those a few months ago 
when I wrote some patches, as I found a mix of them in the pages, and 
wasn't sure which form was more correct.

Cheers,

Alex

> 
>> +.\" ...along with a request to call when one runs into it:
>> +.\" https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/alpha/include/uapi/asm/resource.h#n15
>>   .SH BUGS
>>   In older Linux kernels, the
>>   .B SIGXCPU
> 
> Thank you for your patience with my comments.  I hope they've been
> helpful.
> 
> Regards,
> Branden
> 
> [1] vdso(7) may be an exception.
> [2] https://booksite.elsevier.com/9780124077263/downloads/historial%20perspectives/section_4.16.pdf
> [3] clone(2), syscall(2), and exec(3) may be exceptions.
> [4] https://sparc.org/timeline/
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH v3] getrlimit.2: old_getrlimit/ugetrlimit and RLIM_INFINITY discrepancies

[Eugene Syromyatnikov]

On Fri, Jul 30, 2021 at 12:35 AM G. Branden Robinson
<g.branden.robinson@gmail.com> wrote:
>
> Hi, Eugene!
>
> I thought I'd offer some style suggestions since Alex hasn't yet.

Thanks, it seems like my sense of English grammar was absent on the
day the patch was conceived more than usual.

> At 2021-07-29T17:44:01+0200, Eugene Syromyatnikov wrote:
> > +The corresponding infinity value constant is provided in
> > +.I <linux/resource.h>
> > +as
> > +.BR RLIM64_INFINITY.
> > +.PP
> > +Original Linux implementation used signed types for limits; that was changed
>
> Grammatically, you need an article at the beginning of this sentence.
> More broadly, however, what constitutes "*the* original Linux
> implementation" may not be well-defined and is not as relevant to the
> discussion as Linux kernels that were widely deployed.  The earliest
> conveivable Linux attested, what Torvalds produced on his 80386 in 1991
> ("Freax") is less important than Linux 2.4.
>
> So I would recast and use semantic newlines [see man-pages(7)]:
>
>         Linux 2.4 and earlier used signed types for limits;
>         that was changed
>
> Alex will surely direct you to the semantic newline advice in
> man-pages(7).
>
>    Use semantic newlines
>        In the source of a manual page, new sentences should be started
>        on new lines, and long sentences should  split  into  lines  at
>        clause  breaks  (commas,  semicolons, colons, and so on).  This
>        convention, sometimes known as "semantic  newlines",  makes  it
>        easier to see the effect of patches, which often operate at the
>        level of individual sentences or sentence clauses.
>
> I won't point out every instance where a semantic newline is preferred.
>
> > +(along with the value of the
> > +.B RLIM_INFINITY
> > +constant)
>
> I see there is some precedent in the Linux man-pages to call a
> preprocessor symbol that is replaced with a C language literal a
> "constant".  I would not employ this usage myself, since C has the
> "const" type qualifier that suggests, and is is widely interpreted, as
> "constant".  I think it would be helpful if we referred to as "constant"
> only C objects bearing such a declaration.  Does anyone think this would
> be a worthwhile shift in usage?  (The most important virtue that
> constants in the sense I'm using them have over preprocessor symbols is
> that the former survive the translation process into executable format,
> and (if not optimized out) will appear in a symbol table, which means a
> debugger can know about them.)

I'd stick with the current "constant" usage for brevity: system
headers do not tend to employ const symbols, especially
kernel-provided ones, for reasons, so "constant" meaning is more or
less clear in the section 2 with that regard, albeit not totally
technically sound with respect to the C language.

> > +.\" http://repo.or.cz/davej-history.git/blobdiff/129f8758d8c41e0378ace0b6e2f56bbb8a1ec694..15305d2e69c3a838bacd78962c07077d2821f255:/include/linux/resource.h
> > +during 2.4 development cycle, as it wasn't compatible
>
> s/during/& the/
>
> > +with Single UNIX Specification.
>
> s/with/& the/
>
> > +However, in order to preserve backward compatibility, the routine
>
> s/routine/function/ ?

I followed syscalls(2) naming convention here.

>
> > +.IR sys_old_getrlimit
> > +has been implemented under
>
> s/has been/was/
> s/under/using the/
>
> > +.B __NR_getrlimit
> > +syscall slot, with infinity checks being performed against hard-coded 0x7fffffff
>
> s/hard-coded/a literal/
>
> > +value, and the routine
>
> s/the routine//
> (it will be clear from context that this is another function)
>
> > +.I sys_getrlimit
> > +has been exposed under a new name,
>
> s/has been/was/
> s/exposed/made available/
>
> > +.BR ugetrlimit ().
> > +Note that most newer architectures don't have the latter, with
>
> s/Note that most/Most/
>
> I call this a "Kemper notectomy", after my colleague in groff
> development, Dave Kemper, who has pointed out that we tend to massively
> overuse the phrase "note that" in software documentation.  We write for
> impatient readers.  Everything we say in a manual should be worthy of
> note; if it is not, it should be deleted or moved to a place in the text
> reserved for supplemental commentary (a footnote; a (sub)section entitled
> "Background", "History", or "Notes"; or similar).

This is literally the "Notes" section, though.

> > +.BR getrlimit ()
> > +providing proper implementation.
>
> What's "proper" about it?  That it's unsigned, or that it's conforming?
> Say so.  Again, an article is needed.
>
> s/proper/a conforming/
>
> > +Also worth noting that several architectures decided not to change
>
> I'd condense this.
>
> s/Also worth noting that/However,
> /
>
> > +.B RLIM_INFINITY
> > +value: 32-bit mips and sparc (but not 64-bit variants, that switched
>
> s/mips/MIPS/
>
> The Linux man-pages are mostly consistent about this casing[1], and it
> is normative[2].
>
> s/sparc/SPARC/
>
> The Linux man-pages are mostly consistent about this casing[3], and it
> is normative[4].
>
> > +to the new value of (~0UL)) retained the old 0x7fffffff value,
> > +and alpha retained 0x7ffffffffffffffful.
>
> s/alpha/Alpha/
>
> You can probably guess what I'm going to say.  ;-)
>
> > +.\" ...along with a request to call when one runs into it:
> > +.\" https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/alpha/include/uapi/asm/resource.h#n15
> >  .SH BUGS
> >  In older Linux kernels, the
> >  .B SIGXCPU
>
> Thank you for your patience with my comments.  I hope they've been
> helpful.

They indeed are.

> Regards,
> Branden
>
> [1] vdso(7) may be an exception.
> [2] https://booksite.elsevier.com/9780124077263/downloads/historial%20perspectives/section_4.16.pdf
> [3] clone(2), syscall(2), and exec(3) may be exceptions.
> [4] https://sparc.org/timeline/



-- 
Eugene Syromyatnikov
mailto:evgsyr@gmail.com
xmpp:esyr@jabber.{ru|org}

Re: [PATCH v3] getrlimit.2: old_getrlimit/ugetrlimit and RLIM_INFINITY discrepancies

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1864 bytes --]

At 2021-07-30T02:14:56+0200, Eugene Syromyatnikov wrote:
> On Fri, Jul 30, 2021 at 12:35 AM G. Branden Robinson
> I'd stick with the current "constant" usage for brevity: system
> headers do not tend to employ const symbols, especially
> kernel-provided ones, for reasons, so "constant" meaning is more or
> less clear in the section 2 with that regard, albeit not totally
> technically sound with respect to the C language.

That's fair.  I don't expect all my reformist suggestions to be adopted.
:)

> > > +However, in order to preserve backward compatibility, the routine
> >
> > s/routine/function/ ?
> 
> I followed syscalls(2) naming convention here.

Also a fair point.  Yes, I see that usage is fairly thick in the "NOTES"
section.

> > I call this a "Kemper notectomy", after my colleague in groff
> > development, Dave Kemper, who has pointed out that we tend to
> > massively overuse the phrase "note that" in software documentation.
> > We write for impatient readers.  Everything we say in a manual
> > should be worthy of note; if it is not, it should be deleted or
> > moved to a place in the text reserved for supplemental commentary (a
> > footnote; a (sub)section entitled "Background", "History", or
> > "Notes"; or similar).
> 
> This is literally the "Notes" section, though.

True--I wasn't aware of that before.  But by that token, you could say
that the "note that" phrase is now redundant for a different reason. ;-)

It's not a big deal--I mention it because I've found it a useful prompt
to myself when writing: when I want to say, "note that", what am I
_really_ trying to say?  "Pay attention here"?  "Danger, Will
Robinson!"?  Usually I wind up either dropping "note that" or recasting
the sentence to more clearly motivate why a statement is worthy of
special attention.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]