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

On Fri, Jul 30, 2021 at 12:35 AM G. Branden Robinson
[off-list ref] 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:

quoted

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

quoted

+(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

+.\" 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

+with Single UNIX Specification.

s/with/& the/

quoted

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

s/routine/function/ ?

I followed syscalls(2) naming convention here.

quoted

+.IR sys_old_getrlimit
+has been implemented under

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

quoted

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

s/hard-coded/a literal/

quoted

+value, and the routine

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

quoted

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

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

quoted

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

quoted

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

+Also worth noting that several architectures decided not to change

I'd condense this.

s/Also worth noting that/However,
/

quoted

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

quoted

+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

+.\" ...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}