From 090fdddb4342f92a1dbeba687462f4bcee816232 Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Mon, 17 May 2021 15:31:08 +1200
Subject: [PATCH] memfd_create.2, mmap.2, shmget.2: Document the EPERM for huge
 page allocations

This error can occur if the caller is does not have CAP_IPC_LOCK
and is not a member of the sysctl_hugetlb_shm_group.

Reported-by: Yang Xu <xuyang2018.jy@fujitsu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man2/memfd_create.2 | 13 +++++++++++++
 man2/mmap.2         | 12 ++++++++++++
 man2/shmget.2       |  8 +++++++-
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/man2/memfd_create.2 b/man2/memfd_create.2
index aaaeb1b7f..ee9fa8aa6 100644
--- a/man2/memfd_create.2
+++ b/man2/memfd_create.2
@@ -201,6 +201,19 @@ The
 .BR memfd_create ()
 system call first appeared in Linux 3.17;
 glibc support was added in version 2.27.
+.TP
+.B EPERM
+The
+.B MFD_HUGETLB
+flag was specified, but the caller was not privileged (did not have the
+.B CAP_IPC_LOCK
+capability)
+and is not a member of the
+.I sysctl_hugetlb_shm_group
+group; see the description of
+.I /proc/sys/vm/sysctl_hugetlb_shm_group
+in
+.BR proc (5).
 .SH CONFORMING TO
 The
 .BR memfd_create ()
diff --git a/man2/mmap.2 b/man2/mmap.2
index 03f2eeb2c..4ee2f4f96 100644
--- a/man2/mmap.2
+++ b/man2/mmap.2
@@ -628,6 +628,18 @@ was mounted no-exec.
 The operation was prevented by a file seal; see
 .BR fcntl (2).
 .TP
+.B EPERM
+The
+.B MAP_HUGETLB
+flag was specified, but the caller was not privileged (did not have the
+.B CAP_IPC_LOCK
+capability)
+and is not a member of the
+.I sysctl_hugetlb_shm_group
+group; see the description of
+.I /proc/sys/vm/sysctl_hugetlb_shm_group
+in
+.TP
 .B ETXTBSY
 .B MAP_DENYWRITE
 was set but the object specified by
diff --git a/man2/shmget.2 b/man2/shmget.2
index 757b7b7f1..6e9995e81 100644
--- a/man2/shmget.2
+++ b/man2/shmget.2
@@ -273,7 +273,13 @@ The
 .B SHM_HUGETLB
 flag was specified, but the caller was not privileged (did not have the
 .B CAP_IPC_LOCK
-capability).
+capability)
+and is not a member of the
+.I sysctl_hugetlb_shm_group
+group; see the description of
+.I /proc/sys/vm/sysctl_hugetlb_shm_group
+in
+.BR proc (5).
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, SVr4.
 .\" SVr4 documents an additional error condition EEXIST.