1.\" 2.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> 3.\" Copyright (c) 2021 The FreeBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Parts of this documentation were written by 7.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship 8.\" from the FreeBSD Foundation. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd January 23, 2021 34.Dt VM_MAP_PROTECT 9 35.Os 36.Sh NAME 37.Nm vm_map_protect 38.Nd apply protection bits to a virtual memory region 39.Sh SYNOPSIS 40.In sys/param.h 41.In vm/vm.h 42.In vm/vm_map.h 43.Ft int 44.Fo vm_map_protect 45.Fa "vm_map_t map" 46.Fa "vm_offset_t start" 47.Fa "vm_offset_t end" 48.Fa "vm_prot_t new_prot" 49.Fa "vm_prot_t new_maxprot" 50.Fa "int flags" 51.Fc 52.Sh DESCRIPTION 53The 54.Fn vm_map_protect 55function sets the protection bits and maximum protection bits of the address 56region bounded by 57.Fa start 58and 59.Fa end 60within the map 61.Fa map . 62.Pp 63If the 64.Fa flags 65argument has the 66.Dv VM_MAP_PROTECT_SET_PROT 67bit set, then the effective protection is set to 68.Fa new_prot . 69.Pp 70If the 71.Fa flags 72argument has the 73.Dv VM_MAP_PROTECT_SET_MAXPROT 74bit set, then the maximum protection is set to 75.Fa new_maxprot . 76Protection bits not included into 77.Fa new_maxprot 78will be cleared from existing entries. 79.Pp 80The values specified by 81.Fa new_prot 82and 83.Fa new_maxprot 84are not allowed to include any protection bits that are not set in existing 85.Va max_protection 86on every entry within the range. 87The operation will fail if this condition is violated. 88For instance, this prevents upgrading a shared mapping of a read-only file 89from read-only to read-write. 90.Pp 91The specified range must not contain sub-maps. 92.Sh IMPLEMENTATION NOTES 93The function acquires a lock on the 94.Fa map 95for the duration, by calling 96.Xr vm_map_lock 9 . 97Also, any in-progress wiring operation on the map affecting the specified 98range will cause 99.Nm 100to sleep, waiting for completion. 101.Sh RETURN VALUES 102.Bl -tag -width "Dv KERN_PROTECTION_FAILURE" 103.It Dv KERN_SUCCESS 104The specified protection bits were set successfully. 105.It Dv KERN_INVALID_ARGUMENT 106A sub-map entry was encountered in the range, 107.It Dv KERN_PROTECTION_FAILURE 108The value of 109.Fa new_prot 110or 111.Fa new_maxprot 112exceed 113.Va max_protection 114for an entry within the range. 115.It Dv KERN_PROTECTION_FAILURE 116The map does not allow simultaneous setting of write and execute permissions, 117but 118.Fa new_prot 119has both 120.Dv VM_PROT_WRITE 121and 122.Dv VM_PROT_EXECUTE 123set. 124.It Dv KERN_RESOURCE_SHORTAGE 125A copy-on-write mapping is transitioned from read-only to 126read-write, and not enough swap space is available to back the 127copied pages. 128.It Dv KERN_OUT_OF_BOUNDS 129Both new protection and new maximum protection updates were requested, 130but the specified 131.Fa new_prot 132is not a subset of 133.Fa new_maxprot . 134.El 135.Sh SEE ALSO 136.Xr vm_map 9 137.Sh AUTHORS 138This manual page was written by 139.An Bruce M Simpson Aq Mt bms@spc.org . 140