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.Dd January 23, 2021 32.Dt VM_MAP_PROTECT 9 33.Os 34.Sh NAME 35.Nm vm_map_protect 36.Nd apply protection bits to a virtual memory region 37.Sh SYNOPSIS 38.In sys/param.h 39.In vm/vm.h 40.In vm/vm_map.h 41.Ft int 42.Fo vm_map_protect 43.Fa "vm_map_t map" 44.Fa "vm_offset_t start" 45.Fa "vm_offset_t end" 46.Fa "vm_prot_t new_prot" 47.Fa "vm_prot_t new_maxprot" 48.Fa "int flags" 49.Fc 50.Sh DESCRIPTION 51The 52.Fn vm_map_protect 53function sets the protection bits and maximum protection bits of the address 54region bounded by 55.Fa start 56and 57.Fa end 58within the map 59.Fa map . 60.Pp 61If the 62.Fa flags 63argument has the 64.Dv VM_MAP_PROTECT_SET_PROT 65bit set, then the effective protection is set to 66.Fa new_prot . 67.Pp 68If the 69.Fa flags 70argument has the 71.Dv VM_MAP_PROTECT_SET_MAXPROT 72bit set, then the maximum protection is set to 73.Fa new_maxprot . 74Protection bits not included into 75.Fa new_maxprot 76will be cleared from existing entries. 77.Pp 78The values specified by 79.Fa new_prot 80and 81.Fa new_maxprot 82are not allowed to include any protection bits that are not set in existing 83.Va max_protection 84on every entry within the range. 85The operation will fail if this condition is violated. 86For instance, this prevents upgrading a shared mapping of a read-only file 87from read-only to read-write. 88.Pp 89The specified range must not contain sub-maps. 90.Sh IMPLEMENTATION NOTES 91The function acquires a lock on the 92.Fa map 93for the duration, by calling 94.Xr vm_map_lock 9 . 95Also, any in-progress wiring operation on the map affecting the specified 96range will cause 97.Nm 98to sleep, waiting for completion. 99.Sh RETURN VALUES 100.Bl -tag -width "Dv KERN_PROTECTION_FAILURE" 101.It Dv KERN_SUCCESS 102The specified protection bits were set successfully. 103.It Dv KERN_INVALID_ARGUMENT 104A sub-map entry was encountered in the range, 105.It Dv KERN_PROTECTION_FAILURE 106The value of 107.Fa new_prot 108or 109.Fa new_maxprot 110exceed 111.Va max_protection 112for an entry within the range. 113.It Dv KERN_PROTECTION_FAILURE 114The map does not allow simultaneous setting of write and execute permissions, 115but 116.Fa new_prot 117has both 118.Dv VM_PROT_WRITE 119and 120.Dv VM_PROT_EXECUTE 121set. 122.It Dv KERN_RESOURCE_SHORTAGE 123A copy-on-write mapping is transitioned from read-only to 124read-write, and not enough swap space is available to back the 125copied pages. 126.It Dv KERN_OUT_OF_BOUNDS 127Both new protection and new maximum protection updates were requested, 128but the specified 129.Fa new_prot 130is not a subset of 131.Fa new_maxprot . 132.El 133.Sh SEE ALSO 134.Xr vm_map 9 135.Sh AUTHORS 136This manual page was written by 137.An Bruce M Simpson Aq Mt bms@spc.org . 138