Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/vm_map_protect.9
| .\" | .\" | ||||
| .\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> | .\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> | ||||
| .\" Copyright (c) 2021 The FreeBSD Foundation, Inc. | |||||
| .\" All rights reserved. | .\" 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 | .\" Redistribution and use in source and binary forms, with or without | ||||
| .\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||||
| .\" are met: | .\" are met: | ||||
| .\" 1. Redistributions of source code must retain the above copyright | .\" 1. Redistributions of source code must retain the above copyright | ||||
| .\" notice, this list of conditions and the following disclaimer. | .\" notice, this list of conditions and the following disclaimer. | ||||
| .\" 2. Redistributions in binary form must reproduce the above copyright | .\" 2. Redistributions in binary form must reproduce the above copyright | ||||
| .\" notice, this list of conditions and the following disclaimer in the | .\" notice, this list of conditions and the following disclaimer in the | ||||
| .\" documentation and/or other materials provided with the distribution. | .\" documentation and/or other materials provided with the distribution. | ||||
| .\" | .\" | ||||
| .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | ||||
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||||
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||||
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | ||||
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||||
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | ||||
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
| .\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
| .\" | .\" | ||||
| .\" $FreeBSD$ | .\" $FreeBSD$ | ||||
| .\" | .\" | ||||
| .Dd June 20, 2019 | .Dd January 23, 2021 | ||||
| .Dt VM_MAP_PROTECT 9 | .Dt VM_MAP_PROTECT 9 | ||||
| .Os | .Os | ||||
| .Sh NAME | .Sh NAME | ||||
| .Nm vm_map_protect | .Nm vm_map_protect | ||||
| .Nd apply protection bits to a virtual memory region | .Nd apply protection bits to a virtual memory region | ||||
| .Sh SYNOPSIS | .Sh SYNOPSIS | ||||
| .In sys/param.h | .In sys/param.h | ||||
| .In vm/vm.h | .In vm/vm.h | ||||
| .In vm/vm_map.h | .In vm/vm_map.h | ||||
| .Ft int | .Ft int | ||||
| .Fo vm_map_protect | .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 | .Fc | ||||
| .Sh DESCRIPTION | .Sh DESCRIPTION | ||||
| The | The | ||||
| .Fn vm_map_protect | .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 | |||||
emaste: I think it's fine to leave this as "sets". I assume you changed it because the function does… | |||||
| .Fa start | .Fa start | ||||
| and | and | ||||
| .Fa end | .Fa end | ||||
| within the map | 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 . | .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 | .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 | |||||
Done Inline ActionsPerhaps "are not allowed to"? As is (and before your change) it seems unclear to me whether this is something the caller must take care not to violate, or that the function disallows. emaste: Perhaps "are not allowed to"?
As is (and before your change) it seems unclear to me whether… | |||||
| .Va max_protection | .Va max_protection | ||||
| on every entry within the range. | on every entry within the range. | ||||
| Operation is declined if the condition is violated. | |||||
markjUnsubmitted Done Inline Actions"The operation" I would change "is declined" to "will fail" and "the condition" to "this condition". markj: "The operation"
I would change "is declined" to "will fail" and "the condition" to "this… | |||||
| For instance, this prevents upgrading shared mapping of a file opened | |||||
| read-only, to writeable. | |||||
markjUnsubmitted Done Inline Actions"a shared mapping" "of a read-only file from read-only to read-write" markj: "a shared mapping"
"of a read-only file from read-only to read-write" | |||||
| .Pp | .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 | .Sh IMPLEMENTATION NOTES | ||||
| The function acquires a lock on the | The function acquires a lock on the | ||||
| .Fa map | .Fa map | ||||
| for the duration, by calling | for the duration, by calling | ||||
| .Xr vm_map_lock 9 . | .Xr vm_map_lock 9 . | ||||
| Also, any in-progress wiring operation on the map affecting the specified | |||||
Done Inline ActionsMaybe something like emaste: Maybe something like
"Also, any in-progress wiring operation on the map affecting the… | |||||
| range will cause | |||||
| .Nm | |||||
| to sleep, waiting for completion. | |||||
| .Sh RETURN VALUES | .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 | .Fa new_prot | ||||
| would exceed | or | ||||
| .Fa new_maxprot | |||||
| exceed | |||||
| .Va max_protection | .Va max_protection | ||||
| for an entry within the range, | for an entry within the range. | ||||
| .Dv KERN_PROTECTION_FAILURE | .It Dv KERN_PROTECTION_FAILURE | ||||
Done Inline Actions"The map does not allow ..." I think is clearer emaste: "The map does not allow ..." I think is clearer | |||||
| is returned. | The map does not allow simultaneous setting of write and execute permissions, | ||||
Done Inline ActionsDrop If as above, "Both new protection and..." emaste: Drop If as above, "Both new protection and..."
Or maybe Both `VM_MAP_PROTECT_SET_PROT` and… | |||||
| 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 for backing the | |||||
markjUnsubmitted Done Inline Actionss/for backing/to back/ markj: s/for backing/to back/ | |||||
| copied pages. | |||||
| .It Dv KERN_OUT_OF_BOUNDS | |||||
| Both new protection and new maximum protection update was requested, | |||||
markjUnsubmitted Done Inline Actions"... protection updates were requested" markj: "... protection updates were requested" | |||||
| but specified | |||||
markjUnsubmitted Done Inline Actions"but the specified" markj: "but the specified" | |||||
| .Fa new_prot | |||||
| is not a subset of | |||||
| .Fa new_maxprot . | |||||
| .Sh SEE ALSO | .Sh SEE ALSO | ||||
| .Xr vm_map 9 | .Xr vm_map 9 | ||||
| .Sh AUTHORS | .Sh AUTHORS | ||||
| This manual page was written by | This manual page was written by | ||||
| .An Bruce M Simpson Aq Mt bms@spc.org . | .An Bruce M Simpson Aq Mt bms@spc.org . | ||||
I think it's fine to leave this as "sets". I assume you changed it because the function does not necessarily set both. Because it's entirely dependent on the function's arguments I think it's still reasonable to say sets. To me "may set" implies that vm_map_protect will itself decide if one/both will be set.