From 8fca0c8a0e15d921e265cfa3fc3258a2fe52ac42 Mon Sep 17 00:00:00 2001
From: deraadt <deraadt@openbsd.org>
Date: Sun, 21 Jan 2024 17:46:03 +0000
Subject: [PATCH] update docs on madvise/msync/minherit behaviour in relation
 to immutable memory; ok kettenis

---
 lib/libc/sys/madvise.2    | 32 ++++++++++++++++++++++++++++++--
 lib/libc/sys/mimmutable.2 | 13 ++++++++++---
 lib/libc/sys/minherit.2   | 16 ++++++++++++++--
 lib/libc/sys/msync.2      | 11 +++++++++--
 4 files changed, 63 insertions(+), 9 deletions(-)

diff --git a/lib/libc/sys/madvise.2 b/lib/libc/sys/madvise.2
index eed34f56f39..d62f110f68b 100644
--- a/lib/libc/sys/madvise.2
+++ b/lib/libc/sys/madvise.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: madvise.2,v 1.22 2019/12/26 01:01:06 jsg Exp $
+.\"	$OpenBSD: madvise.2,v 1.23 2024/01/21 17:46:03 deraadt Exp $
 .\"	$NetBSD: madvise.2,v 1.7 1995/12/27 21:17:02 jtc Exp $
 .\"
 .\" Copyright (c) 1991, 1993
@@ -30,7 +30,7 @@
 .\"
 .\"	@(#)madvise.2	8.1 (Berkeley) 6/9/93
 .\"
-.Dd $Mdocdate: December 26 2019 $
+.Dd $Mdocdate: January 21 2024 $
 .Dt MADVISE 2
 .Os
 .Sh NAME
@@ -88,7 +88,31 @@ If successful, the
 .Fn posix_madvise
 function will return zero.
 Otherwise an error number will be returned to indicate the error.
+.Sh ERRORS
+.Fn madvise
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The specified
+.Fa behav
+argument was invalid.
+.It Bq Er EINVAL
+The
+.Fa addr
+parameter was not page aligned or
+.Fa addr
+and
+.Fa size
+specify a region that would extend beyond the end of the address space.
+.It Bq Er EPERM
+The
+.Fa addr
+and
+.Fa len
+parameters specify a region which contains at least one page marked immutable.
+.El
 .Sh SEE ALSO
+.Xr mimmutable 2 ,
 .Xr minherit 2 ,
 .Xr mprotect 2 ,
 .Xr msync 2 ,
@@ -98,6 +122,10 @@ The
 .Fn posix_madvise
 system call conforms to
 .St -p1003.1-2008 .
+.Pp
+The
+.Er EPERM
+failure conditions described are an extension to this specification.
 .Sh HISTORY
 The
 .Fn madvise
diff --git a/lib/libc/sys/mimmutable.2 b/lib/libc/sys/mimmutable.2
index 03fff5cc747..96b7641ae13 100644
--- a/lib/libc/sys/mimmutable.2
+++ b/lib/libc/sys/mimmutable.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mimmutable.2,v 1.4 2024/01/20 13:19:37 deraadt Exp $
+.\"	$OpenBSD: mimmutable.2,v 1.5 2024/01/21 17:46:03 deraadt Exp $
 .\"
 .\" Copyright (c) 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"	@(#)mimmutable.2	8.1 (Berkeley) 6/9/93
 .\"
-.Dd $Mdocdate: January 20 2024 $
+.Dd $Mdocdate: January 21 2024 $
 .Dt MIMMUTABLE 2
 .Os
 .Sh NAME
@@ -45,9 +45,12 @@ The
 system call
 changes currently mapped pages in the region to be marked immutable,
 which means their protection or mapping may not be changed in the future.
+Most requests to
+.Xr madvise 2 ,
+.Xr minherit 2 ,
 .Xr mmap 2 ,
 .Xr mprotect 2 ,
-and
+.Xr msync 2 , and
 .Xr munmap 2
 to pages marked immutable will return with error
 .Er EPERM .
@@ -71,8 +74,12 @@ The virtual address range specified by the
 and
 .Fa len
 arguments is not valid.
+.It Bq Er EPERM
+At least one page has inheritance of
+.Dv MAP_INHERIT_ZERO .
 .El
 .Sh SEE ALSO
+.Xr minherit 2 ,
 .Xr mmap 2 ,
 .Xr mprotect 2 ,
 .Xr munmap 2
diff --git a/lib/libc/sys/minherit.2 b/lib/libc/sys/minherit.2
index 7c9dce7f417..e814a0a7f9b 100644
--- a/lib/libc/sys/minherit.2
+++ b/lib/libc/sys/minherit.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: minherit.2,v 1.16 2019/01/11 18:46:30 deraadt Exp $
+.\"	$OpenBSD: minherit.2,v 1.17 2024/01/21 17:46:03 deraadt Exp $
 .\"
 .\" Copyright (c) 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"	@(#)minherit.2	8.1 (Berkeley) 6/9/93
 .\"
-.Dd $Mdocdate: January 11 2019 $
+.Dd $Mdocdate: January 21 2024 $
 .Dt MINHERIT 2
 .Os
 .Sh NAME
@@ -73,6 +73,17 @@ The
 .Fn minherit
 system call will fail if:
 .Bl -tag -width Er
+.It Bq Er EPERM
+The
+.Fa addr
+and
+.Fa len
+parameters specify a region that contains
+at least one page which is immutable, or
+.Dv MAP_INHERIT_ZERO
+is being requested on a page without
+.Dv PROT_WRITE
+permission.
 .It Bq Er EINVAL
 The virtual address range specified by the
 .Fa addr
@@ -86,6 +97,7 @@ argument is invalid.
 .El
 .Sh SEE ALSO
 .Xr madvise 2 ,
+.Xr mimmutable 2 ,
 .Xr mprotect 2 ,
 .Xr msync 2 ,
 .Xr munmap 2
diff --git a/lib/libc/sys/msync.2 b/lib/libc/sys/msync.2
index 9293653e9c3..2660fa69b5d 100644
--- a/lib/libc/sys/msync.2
+++ b/lib/libc/sys/msync.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: msync.2,v 1.29 2021/06/30 18:46:49 schwarze Exp $
+.\"	$OpenBSD: msync.2,v 1.30 2024/01/21 17:46:03 deraadt Exp $
 .\"	$NetBSD: msync.2,v 1.8 1995/10/12 15:41:09 jtc Exp $
 .\"
 .\" Copyright (c) 1991, 1993
@@ -30,7 +30,7 @@
 .\"
 .\"	@(#)msync.2	8.1 (Berkeley) 6/9/93
 .\"
-.Dd $Mdocdate: June 30 2021 $
+.Dd $Mdocdate: January 21 2024 $
 .Dt MSYNC 2
 .Os
 .Sh NAME
@@ -88,6 +88,12 @@ parameter was not page aligned or
 and
 .Fa size
 specify a region that would extend beyond the end of the address space.
+.It Bq Er EPERM
+The
+.Fa addr
+and
+.Fa len
+parameters specify a region which contains at least one page marked immutable.
 .It Bq Er ENOMEM
 Addresses in the specified region are outside the range allowed
 for the address space of the process, or specify one or more pages
@@ -97,6 +103,7 @@ An I/O error occurred while writing.
 .El
 .Sh SEE ALSO
 .Xr madvise 2 ,
+.Xr mimmutable 2 ,
 .Xr minherit 2 ,
 .Xr mprotect 2 ,
 .Xr munmap 2
-- 
2.20.1