Re: [PATCH] prctl.2, proc.5: Document VMA naming

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 5207 bytes --]



On 1/3/23 11:02, Alejandro Colomar wrote:
> Hello Nick,
> 
> On 1/3/23 04:28, Nick Gregory wrote:
>> Bring in prctl man page changes from the patch set by Colin Cross
>> <ccross@google.com> [0], and document the corresponding virtual names in proc.
>>
>> Signed-off-by: Nick Gregory <nick@nickgregory.me>
> 
> Please add Colin (and whoever was interested in the patch, which seems to be at 
> least Suren and Kees) to the Cc tags.
> 
> Cheers,
> Alex
> 
>>
>> [0] https://lore.kernel.org/linux-mm/20211019215511.3771969-2-surenb@google.com/
>> ---
>>   man2/prctl.2 | 35 +++++++++++++++++++++++++++++++++++
>>   man5/proc.5  | 14 ++++++++++++++
>>   2 files changed, 49 insertions(+)
>>
>> diff --git a/man2/prctl.2 b/man2/prctl.2
>> index 74f86ff49..82b8a1b02 100644
>> --- a/man2/prctl.2
>> +++ b/man2/prctl.2
>> @@ -769,6 +769,41 @@ This feature is available only if the kernel is built 
>> with the
>>   .B CONFIG_CHECKPOINT_RESTORE
>>   option enabled.
>>   .RE
>> +.\" prctl PR_SET_VMA
>> +.TP
>> +.BR PR_SET_VMA " (since Linux 5.17)"
>> +.\" Commit 9a10064f5625d5572c3626c1516e0bebc6c9fe9b
>> +Sets an attribute specified in
>> +.I arg2
>> +for virtual memory areas starting from
>> +the address specified in
>> +.I arg3
>> +and spanning the size specified in
>> +.IR arg4 .
>> +.I arg5
>> +specifies the value of the attribute to be set.
>> +.IP
>> +Note that assigning an attribute to a virtual memory
>> +area might prevent it from being merged with adjacent virtual

Please use semantic newlines.

man-pages(7):
    Use semantic newlines
        In  the source of a manual page, new sentences should be started on new
        lines, long sentences should be split into lines at clause breaks (com‐
        mas, semicolons, colons, and so on), and long clauses should  be  split
        at  phrase  boundaries.   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, clauses, or phrases.


>> +memory areas due to the difference in that attribute's value.
>> +.IP
>> +Currently,
>> +.I arg2
>> +must be one of:
>> +.RS
>> +.TP
>> +.B PR_SET_VMA_ANON_NAME
>> +Set a name for anonymous virtual memory areas.
>> +.I arg5
>> +should be a pointer to a null-terminated string containing the
>> +name. The name length including null byte cannot exceed
>> +80 bytes. If
>> +.I arg5
>> +is NULL, the name of the appropriate
>> +anonymous virtual memory areas will be reset.
>> +The name can contain only printable ascii characters
>> +(including space), except '[',']','\','$' and '`'.

You need to escape several characters here.  See groff_char(7):

          ┌──────────────────────────────────────────────────────────────────┐
          │Keycap   Appearance and meaning   Special character and meaning   │
          ├──────────────────────────────────────────────────────────────────┤
          │"        " neutral double quote   \[dq] neutral double quote      │
          │'        ’ closing single quote   \[aq] neutral apostrophe        │
          │-        ‐ hyphen                 \- or \[-] minus sign/Unix dash │
          │\        (escape character)       \e or \[rs] reverse solidus     │
          │^        ˆ modifier circumflex    \(ha circumflex/caret/“hat”     │
          │`        ‘ opening single quote   \(ga grave accent               │
          │~        ˜ modifier tilde         \(ti tilde                      │
          └──────────────────────────────────────────────────────────────────┘

BTW, although that table doesn't show it, \(dq and \(aq also work for double and 
single quotes.  Branden, why is that table inconsistent with the style of 
special characters?

>> +.RE
>>   .\" prctl PR_MPX_ENABLE_MANAGEMENT
>>   .TP
>>   .BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 
>> 3.19, removed in Linux 5.4; only on x86)"
>> diff --git a/man5/proc.5 b/man5/proc.5
>> index 65a4c38e3..e0a64d486 100644
>> --- a/man5/proc.5
>> +++ b/man5/proc.5
>> @@ -1372,6 +1372,20 @@ See
>>   .TP
>>   .I [heap]
>>   The process's heap.
>> +.TP
>> +.IR [anon: name ] " (since Linux 5.17)"
>> +.\" Commit 9a10064f5625d5572c3626c1516e0bebc6c9fe9b
>> +A named private anonymous mapping.
>> +Set with
>> +.BR prctl (2)
>> +.BR PR_SET_VMA_ANON_NAME .
>> +.TP
>> +.IR [anon_shmem: name ] " (since Linux 6.2)"
>> +.\" Commit d09e8ca6cb93bb4b97517a18fbbf7eccb0e9ff43
>> +A named shared anonymous mapping.
>> +Set with
>> +.BR prctl (2)
>> +.BR PR_SET_VMA_ANON_NAME .
>>   .in
>>   .RE
>>   .IP
> 

-- 
<http://www.alejandro-colomar.es/>

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