[patch] Clarify that MAP_POPULATE is best-effort

[patch] Clarify that MAP_POPULATE is best-effort

[Bruce Merry]

As discussed on linux-mm
(https://marc.info/?l=linux-mm&m=161528594100612&w=2), MAP_POPULATE can
fail silently if the hugetlb cgroup settings allow huge page reservation
but prevents huge pages being allocated.

Closes https://bugzilla.kernel.org/show_bug.cgi?id=212153.
---
 man2/mmap.2 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man2/mmap.2 b/man2/mmap.2
index 164ba196e..03f2eeb2c 100644
--- a/man2/mmap.2
+++ b/man2/mmap.2
@@ -400,6 +400,11 @@ private writable mappings.
 Populate (prefault) page tables for a mapping.
 For a file mapping, this causes read-ahead on the file.
 This will help to reduce blocking on page faults later.
+The
+.BR mmap ()
+call doesn't fail if the mapping cannot be populated (for example, due
+to limitations on the number of mapped huge pages when using
+.BR MAP_HUGETLB ).
 .BR MAP_POPULATE
 is supported for private mappings only since Linux 2.6.23.
 .TP
-- 
2.25.1

Re: [patch] Clarify that MAP_POPULATE is best-effort

[Michael Kerrisk (man-pages)]

Hello Bruce,

On 3/23/21 8:48 AM, Bruce Merry wrote:
> As discussed on linux-mm
> (https://marc.info/?l=linux-mm&m=161528594100612&w=2), MAP_POPULATE can
> fail silently if the hugetlb cgroup settings allow huge page reservation
> but prevents huge pages being allocated.
> 
> Closes https://bugzilla.kernel.org/show_bug.cgi?id=212153.
> ---
>  man2/mmap.2 | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/man2/mmap.2 b/man2/mmap.2
> index 164ba196e..03f2eeb2c 100644
> --- a/man2/mmap.2
> +++ b/man2/mmap.2
> @@ -400,6 +400,11 @@ private writable mappings.
>  Populate (prefault) page tables for a mapping.
>  For a file mapping, this causes read-ahead on the file.
>  This will help to reduce blocking on page faults later.
> +The
> +.BR mmap ()
> +call doesn't fail if the mapping cannot be populated (for example, due
> +to limitations on the number of mapped huge pages when using
> +.BR MAP_HUGETLB ).
>  .BR MAP_POPULATE
>  is supported for private mappings only since Linux 2.6.23.
>  .TP

Thanks. Patch applied.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/