share/man/man9/vm_map_protect.9

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