getrlimit.2: old_getrlimit/ugetrlimit and RLIM_INFINITY discrepancies
PATCH v3 1/1 getrlimit.2: old_getrlimit/ugetrlimit and RLIM_INFINITY discrepancies
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.
--- man2/getrlimit.2 | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+)
man2/getrlimit.2 +31 -0
@@ -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
Signature · 1 line
2.1.4
Hi, Eugene!
I thought I'd offer some style suggestions since Alex hasn't yet.
man2/getrlimit.2 The name of the glibc wrapper function is · line 654
Quoted 6 lines · Eugene Syromyatnikov
man2/getrlimit.2 +6
-0+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.
man2/getrlimit.2 The name of the glibc wrapper function is · line 657
Quoted 3 lines
man2/getrlimit.2 +3
-0+(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.)
Quoted 2 lines
+.\" 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/
Quoted 1 line
+with Single UNIX Specification.
s/with/& the/
Quoted 1 line
+However, in order to preserve backward compatibility, the routine
s/routine/function/ ?
Quoted 2 lines
+.IR
sys_old_getrlimit
+has been implemented under
s/has been/was/
s/under/using the/
Quoted 2 lines
+.B
__NR_getrlimit
+syscall slot, with infinity checks being performed against hard-coded0x7fffffff
s/hard-coded/a literal/
Quoted 1 line
+value, and the routine
s/the routine//
(it will be clear from context that this is another function)
Quoted 2 lines
+.I
sys_getrlimit
+has been exposed under a new name,
s/has been/was/
s/exposed/made available/
Quoted 2 lines
+.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).
Quoted 2 lines
+.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/
Quoted 1 line
+Also worth noting that several architectures decided not to change
I'd condense this.
s/Also worth noting that/However,
/
Quoted 2 lines
+.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].
man2/getrlimit.2 The name of the glibc wrapper function is · line 677
Quoted 2 lines
man2/getrlimit.2 +2
-0+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. ;-)
Quoted 5 lines
+.\" ...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/
Hi Branden,
Thanks for reviewing this!
I didn't have more time today.
Also seeing reviews from different people helps improving my reviews too :)
Quoted 19 lines · G. Branden Robinson
Hi, Eugene!
I thought I'd offer some style suggestions since Alex hasn't yet.
man2/getrlimit.2 The name of the glibc wrapper function is · line 654
Quoted 6 lines · Eugene Syromyatnikov
man2/getrlimit.2 +6
-0+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 changedGrammatically, 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.
Quoted 7 lines
So I would recast and use semantic newlines [see man-pages(7)]:
Linux 2.4 and earlier used signed types for limits; that was changedAlex will surely direct you to the semantic newline advice in man-pages(7).
:-)
Quoted 11 lines
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.
Quoted 15 lines
man2/getrlimit.2 The name of the glibc wrapper function is · line 657
Quoted 3 lines
man2/getrlimit.2 +3
-0+(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
Quoted 77 lines
Quoted 3 lines
+.\" http://repo.or.cz/davej-history.git/blobdiff/129f8758d8c41e0378ace0b6e2f56bbb8a1ec694..15305d2e69c3a838bacd78962c07077d2821f255:/include/linux/resource.h
+during 2.4 development cycle, as it wasn't compatibles/during/& the/
Quoted 1 line
+with Single UNIX Specification.
s/with/& the/
Quoted 1 line
+However, in order to preserve backward compatibility, the routine
s/routine/function/ ?
Quoted 2 lines
+.IR
sys_old_getrlimit
+has been implemented unders/has been/was/
s/under/using the/Quoted 2 lines
+.B
__NR_getrlimit
+syscall slot, with infinity checks being performed against hard-coded0x7fffffffs/hard-coded/a literal/
Quoted 1 line
+value, and the routine
s/the routine//
(it will be clear from context that this is another function)Quoted 2 lines
+.I
sys_getrlimit
+has been exposed under a new name,s/has been/was/
s/exposed/made available/Quoted 2 lines
+.BR ugetrlimit ().
+Note that most newer architectures don't have the latter, withs/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).
Quoted 2 lines
+.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/
Quoted 1 line
+Also worth noting that several architectures decided not to change
I'd condense this.
s/Also worth noting that/However,
/Quoted 2 lines
+.B
RLIM_INFINITY
+value: 32-bit mips and sparc (but not 64-bit variants, that switcheds/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].
Quoted 6 lines
man2/getrlimit.2 The name of the glibc wrapper function is · line 677
Quoted 2 lines
man2/getrlimit.2 +2
-0+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
Quoted 18 lines
Quoted 6 lines
+.\" ...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 SIGXCPUThank 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/
Signature · 3 lines
Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Quoted 4 lines · G. Branden Robinson
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.
Quoted 33 lines
man2/getrlimit.2 The name of the glibc wrapper function is · line 654
Quoted 6 lines · Eugene Syromyatnikov
man2/getrlimit.2 +6
-0+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 changedGrammatically, 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.
Quoted 15 lines
man2/getrlimit.2 The name of the glibc wrapper function is · line 657
Quoted 3 lines
man2/getrlimit.2 +3
-0+(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.
Quoted 5 lines
Quoted 2 lines
+.\" http://repo.or.cz/davej-history.git/blobdiff/129f8758d8c41e0378ace0b6e2f56bbb8a1ec694..15305d2e69c3a838bacd78962c07077d2821f255:/include/linux/resource.h
+during 2.4 development cycle, as it wasn't compatibles/during/& the/
Quoted 7 lines
Quoted 1 line
+with Single UNIX Specification.
s/with/& the/
Quoted 1 line
+However, in order to preserve backward compatibility, the routine
s/routine/function/ ?
I followed syscalls(2) naming convention here.
Quoted 28 lines
Quoted 3 lines
+.IR
sys_old_getrlimit
+has been implemented unders/has been/was/
s/under/using the/Quoted 2 lines
+.B
__NR_getrlimit
+syscall slot, with infinity checks being performed against hard-coded0x7fffffffs/hard-coded/a literal/
Quoted 1 line
+value, and the routine
s/the routine//
(it will be clear from context that this is another function)Quoted 2 lines
+.I
sys_getrlimit
+has been exposed under a new name,s/has been/was/
s/exposed/made available/Quoted 2 lines
+.BR ugetrlimit ().
+Note that most newer architectures don't have the latter, withs/Note that most/Most/
Quoted 7 lines
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.
Quoted 35 lines
Quoted 2 lines
+.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/
Quoted 1 line
+Also worth noting that several architectures decided not to change
I'd condense this.
s/Also worth noting that/However,
/Quoted 2 lines
+.B
RLIM_INFINITY
+value: 32-bit mips and sparc (but not 64-bit variants, that switcheds/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].
man2/getrlimit.2 The name of the glibc wrapper function is · line 677
Quoted 2 lines
man2/getrlimit.2 +2
-0+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. ;-)
Quoted 8 lines
Quoted 5 lines
+.\" ...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 SIGXCPUThank you for your patience with my comments. I hope they've been helpful.
They indeed are.
Quoted 7 lines
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/
Signature · 3 lines
Eugene Syromyatnikov mailto:[email protected] xmpp:esyr@jabber.{ru|org}
Quoted 6 lines · Eugene Syromyatnikov
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. :)
Quoted 5 lines
Quoted 3 lines
Quoted 1 line
+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.
Quoted 10 lines
Quoted 8 lines
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