Re: [PATCH man-pages] madvise.2: add MADV_GUARD_INSTALL, MADV_GUARD_REMOVE description

[Alejandro Colomar <alx@kernel.org>]

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

Hi Lorenzo,

On Fri, Nov 29, 2024 at 09:32:05AM +0000, Lorenzo Stoakes wrote:
> Lightweight guard region support has been added to Linux 6.13, which adds
> MADV_GUARD_INSTALL and MADV_GUARD_REMOVE flags to the madvise() system
> call. Therefore, update the manpage for madvise() and describe these
> operations.
> 
> Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>

Thanks for the patch.  Please see some comments below.

Have a lovely day!
Alex

> ---
>  man/man2/madvise.2 | 81 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 81 insertions(+)
> 
> diff --git a/man/man2/madvise.2 b/man/man2/madvise.2
> index 4f2210ee2..e539fefe4 100644
> --- a/man/man2/madvise.2
> +++ b/man/man2/madvise.2
> @@ -676,6 +676,79 @@ or secret memory regions created using
>  Note that with
>  .BR MADV_POPULATE_WRITE ,
>  the process can be killed at any moment when the system runs out of memory.
> +.TP
> +.BR MADV_GUARD_INSTALL " (since Linux 6.13)"
> +Install a lightweight guard region into the range specified by
> +.I addr
> +and
> +.IR size ,
> +causing any read or write in the range to result in a fatal
> +.B SIGSEGV
> +signal being raised.
> +.IP
> +If the region maps memory pages they will be cleared as part of the operation,
> +though if
> +.B MADV_GUARD_INSTALL
> +is applied to regions containing pre-existing lightweight guard regions, they
> +are left in place.

Please use semantic newlines.  See man-pages(7):

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p';
   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 (commas, 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  in‐
       dividual sentences, clauses, or phrases.


> +.IP
> +This operation is only supported for writable anonymous private mappings which
> +have not been mlock'd. An
> +.B EINVAL
> +error is returned if it is attempted on any other kind of mapping.
> +.IP
> +This operation is more efficient than mapping a new region of memory
> +.BR PROT_NONE ,
> +as it does not require the establishment of new mappings, instead regions of an
> +existing mapping simply have their page tables manipulated to establish the
> +desired behavior. No additional memory is used.
> +.IP
> +Lightweight guard regions remain on fork (except for any parts which have had
> +.B MADV_WIPEONFORK
> +applied to them), and are not removed by
> +.BR MADV_DONTNEED ,
> +.BR MADV_FREE ,
> +.BR MADV_PAGEOUT ,
> +or
> +.BR MADV_COLD .
> +.IP
> +Attempting to
> +.B mlock()
> +lightweight guard regions will fail, as will
> +.B MADV_POPULATE_READ
> +or
> +.BR MADV_POPULATE_WRITE .
> +.IP
> +If the mapping has its attributes changed, or is split or partially unmapped,
> +any existing guard regions remain in place (except if any are unmapped).
> +.IP
> +If a mapping is moved using
> +.BR mremap() ,

The "()" should not be bold.  They should go with the ','.

> +lightweight guard regions are moved with it.
> +.IP
> +Lightweight guard regions are removed when unmapped, on process teardown, or
> +when the
> +.B MADV_GUARD_REMOVE
> +operation is applied to them.
> +.TP
> +.BR MADV_GUARD_REMOVE " (since Linux 6.13)"
> +Remove any lightweight guard regions which exist in the range specified by
> +.I addr
> +and
> +.IR size .
> +.IP
> +All mappings in the range other than lightweight guard regions are left in place
> +(including mlock'd mappings). The operation is, however, only valid for writable
> +anonymous private mappings, returning an
> +.B EINVAL
> +error otherwise.
> +.IP
> +When lightweight guard regions are removed, they act as empty regions of the
> +containing mapping. Since only writable anonymous private mappings are
> +supported, they therefore become zero-fill-on-demand pages.
> +.IP
> +If any transparent huge pages are encountered in the operation, they are left in
> +place.
>  .SH RETURN VALUE
>  On success,
>  .BR madvise ()
> @@ -787,6 +860,14 @@ or
>  or secret memory regions created using
>  .BR memfd_secret(2) .
>  .TP
> +.B EINVAL
> +.I advice
> +is
> +.B MADV_GUARD_INSTALL
> +or
> +.BR MADV_GUARD_REMOVE ,
> +but the specified address range contains an unsupported mapping.
> +.TP
>  .B EIO
>  (for
>  .BR MADV_WILLNEED )
> -- 
> 2.47.1
> 

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

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