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

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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/