vm_map_protect.9: update after code changes

Reviewed by:	brooks, markj
Discussed with:	emaste
Sponsored by:	The FreeBSD Foundation
MFC after:	3 days
Differential Revision:	https://reviews.freebsd.org/D28311

share/man/man9/vm_map_protect.9

@@ -1,7 +1,12 @@
 .\"
 .\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org>
+.\" Copyright (c) 2021 The FreeBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
+.\" Parts of this documentation were written by
+.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
+.\" from the FreeBSD Foundation.
+.\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
@@ -25,7 +30,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 20, 2019
+.Dd January 23, 2021
 .Dt VM_MAP_PROTECT 9
 .Os
 .Sh NAME
@@ -37,70 +42,95 @@
 .In vm/vm_map.h
 .Ft int
 .Fo vm_map_protect
-.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_prot_t new_prot"
+.Fa "vm_map_t map"
-.Fa "boolean_t set_max"
+.Fa "vm_offset_t start"
+.Fa "vm_offset_t end"
+.Fa "vm_prot_t new_prot"
+.Fa "vm_prot_t new_maxprot"
+.Fa "int flags"
 .Fc
 .Sh DESCRIPTION
 The
 .Fn vm_map_protect
-function sets the protection bits of the address region bounded by
+function sets the protection bits and maximum protection bits of the address
+region bounded by
 .Fa start
 and
 .Fa end
 within the map
-.Fa map
+.Fa map .
-to
+.Pp
+If the
+.Fa flags
+argument has the
+.Dv VM_MAP_PROTECT_SET_PROT
+bit set, then the effective protection is set to
 .Fa new_prot .
-The value specified by
+.Pp
+If the
+.Fa flags
+argument has the
+.Dv VM_MAP_PROTECT_SET_MAXPROT
+bit set, then the maximum protection is set to
+.Fa new_maxprot .
+Protection bits not included into
+.Fa new_maxprot
+will be cleared from existing entries.
+.Pp
+The values specified by
 .Fa new_prot
-may not include any protection bits that are not set in
+and
+.Fa new_maxprot
+are not allowed to include any protection bits that are not set in existing
 .Va max_protection
 on every entry within the range.
+The operation will fail if this condition is violated.
+For instance, this prevents upgrading a shared mapping of a read-only file
+from read-only to read-write.
 .Pp
-If
+The specified range must not contain sub-maps.
-.Fa set_max
-is TRUE,
-.Fa new_prot
-is treated as the new
-.Va max_protection
-setting for each underlying entry.
-Protection bits not included
-.Fa new_prot
-will be cleared from existing entries.
-If
-.Fa set_max
-is FALSE only the
-.Va protection
-field is affected.
-.Pp
-The range MUST be contiguous, and MUST NOT contain sub-maps.
 .Sh IMPLEMENTATION NOTES
 The function acquires a lock on the
 .Fa map
 for the duration, by calling
 .Xr vm_map_lock 9 .
+Also, any in-progress wiring operation on the map affecting the specified
+range will cause
+.Nm
+to sleep, waiting for completion.
 .Sh RETURN VALUES
-The
+.Bl -tag -width "Dv KERN_PROTECTION_FAILURE"
-.Fn vm_map_protect
+.It Dv KERN_SUCCESS
-function returns
+The specified protection bits were set successfully.
-.Dv KERN_SUCCESS
+.It Dv KERN_INVALID_ARGUMENT
-if the protection bits could be set successfully.
+A sub-map entry was encountered in the range,
-.Pp
+.It Dv KERN_PROTECTION_FAILURE
-If a sub-map entry was encountered in the range,
+The value of
-.Dv KERN_INVALID_ARGUMENT
-is returned.
-If the value of
 .Fa new_prot
-would exceed
+or
+.Fa new_maxprot
+exceed
 .Va max_protection
-for an entry within the range,
+for an entry within the range.
-.Dv KERN_PROTECTION_FAILURE
+.It Dv KERN_PROTECTION_FAILURE
-is returned.
+The map does not allow simultaneous setting of write and execute permissions,
-If a copy-on-write mapping is transitioned from read-only to
+but
-read-write, and too little swap space is available for backing the
+.Fa new_prot
-copied pages,
+has both
-.Dv KERN_RESOURCE_SHORTAGE
+.Dv VM_PROT_WRITE
-is returned.
+and
+.Dv VM_PROT_EXECUTE
+set.
+.It Dv KERN_RESOURCE_SHORTAGE
+A copy-on-write mapping is transitioned from read-only to
+read-write, and not enough swap space is available to back the
+copied pages.
+.It Dv KERN_OUT_OF_BOUNDS
+Both new protection and new maximum protection updates were requested,
+but the specified
+.Fa new_prot
+is not a subset of
+.Fa new_maxprot .
 .Sh SEE ALSO
 .Xr vm_map 9
 .Sh AUTHORS