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@xxxxxxxxxx> --- 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. +.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() , +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
