man2/mprotect.2

   1 .\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (C) 1995 Michael Shields <shields@tembel.org>.
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
   7 .\" Modified 1997-05-31 by Andries Brouwer <aeb@cwi.nl>
   8 .\" Modified 2003-08-24 by Andries Brouwer <aeb@cwi.nl>
   9 .\" Modified 2004-08-16 by Andi Kleen <ak@muc.de>
  10 .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and
  11 .\" a much improved example program.
  12 .\"
  13 .TH MPROTECT 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  14 .SH NAME
  15 mprotect, pkey_mprotect \- set protection on a region of memory
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <sys/mman.h>
  22 .PP
  23 .BI "int mprotect(void *" addr ", size_t " len ", int " prot );
  24 .PP
  25 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  26 .B #include <sys/mman.h>
  27 .PP
  28 .BI "int pkey_mprotect(void *" addr ", size_t " len ", int " prot ", int " pkey ");"
  29 .fi
  30 .SH DESCRIPTION
  31 .BR mprotect ()
  32 changes the access protections for the calling process's memory pages
  33 containing any part of the address range in the
  34 interval [\fIaddr\fP,\ \fIaddr\fP+\fIlen\fP\-1].
  35 .I addr
  36 must be aligned to a page boundary.
  37 .PP
  38 If the calling process tries to access memory in a manner
  39 that violates the protections, then the kernel generates a
  40 .B SIGSEGV
  41 signal for the process.
  42 .PP
  43 .I prot
  44 is a combination of the following access flags:
  45 .B PROT_NONE
  46 or a bitwise-or of the other values in the following list:
  47 .TP
  48 .B PROT_NONE
  49 The memory cannot be accessed at all.
  50 .TP
  51 .B PROT_READ
  52 The memory can be read.
  53 .TP
  54 .B PROT_WRITE
  55 The memory can be modified.
  56 .TP
  57 .B PROT_EXEC
  58 The memory can be executed.
  59 .TP
  60 .BR PROT_SEM " (since Linux 2.5.7)"
  61 The memory can be used for atomic operations.
  62 This flag was introduced as part of the
  63 .BR futex (2)
  64 implementation (in order to guarantee the ability to perform atomic
  65 operations required by commands such as
  66 .BR FUTEX_WAIT ),
  67 but is not currently used in on any architecture.
  68 .TP
  69 .BR PROT_SAO " (since Linux 2.6.26)"
  70 .\" commit aba46c5027cb59d98052231b36efcbbde9c77a1d
  71 .\" commit ef3d3246a0d06be622867d21af25f997aeeb105f
  72 The memory should have strong access ordering.
  73 This feature is specific to
  74 the PowerPC architecture
  75 (version 2.06 of the architecture specification adds the SAO CPU feature,
  76 and it is available on POWER 7 or PowerPC A2, for example).
  77 .PP
  78 Additionally (since Linux 2.6.0),
  79 .I prot
  80 can have one of the following flags set:
  81 .TP
  82 .\" mm/mmap.c:
  83 .\"     vm_flags |= calc_vm_prot_bits(prot, pkey) | calc_vm_flag_bits(flags) |
  84 .\"                     mm->def_flags | VM_MAYREAD | VM_MAYWRITE | VM_MAYEXEC;
  85 .\" And calc_vm_flag_bits converts only GROWSDOWN/DENYWRITE/LOCKED.
  86 .B PROT_GROWSUP
  87 Apply the protection mode up to the end of a mapping
  88 that grows upwards.
  89 (Such mappings are created for the stack area on
  90 architectures\(emfor example, HP-PARISC\(emthat
  91 have an upwardly growing stack.)
  92 .\" The VMA is one that was marked with VM_GROWSUP by the kernel
  93 .\" when the stack was created. Note that (unlike VM_GROWSDOWN),
  94 .\" there is no mmap() flag (analogous to MAP_GROWSDOWN) for
  95 .\" creating a VMA that is marked VM_GROWSUP.
  96 .TP
  97 .B PROT_GROWSDOWN
  98 Apply the protection mode down to the beginning of a mapping
  99 that grows downward
 100 (which should be a stack segment or a segment mapped with the
 101 .B MAP_GROWSDOWN
 102 flag set).
 103 .PP
 104 Like
 105 .BR mprotect (),
 106 .BR pkey_mprotect ()
 107 changes the protection on the pages specified by
 108 .IR addr
 109 and
 110 .IR len .
 111 The
 112 .I pkey
 113 argument specifies the protection key (see
 114 .BR pkeys (7))
 115 to assign to the memory.
 116 The protection key must be allocated with
 117 .BR pkey_alloc (2)
 118 before it is passed to
 119 .BR pkey_mprotect ().
 120 For an example of the use of this system call, see
 121 .BR pkeys (7).
 122 .SH RETURN VALUE
 123 On success,
 124 .BR mprotect ()
 125 and
 126 .BR pkey_mprotect ()
 127 return zero.
 128 On error, these system calls return \-1, and
 129 .I errno
 130 is set to indicate the error.
 131 .SH ERRORS
 132 .TP
 133 .B EACCES
 134 The memory cannot be given the specified access.
 135 This can happen, for example, if you
 136 .BR mmap (2)
 137 a file to which you have read-only access, then ask
 138 .BR mprotect ()
 139 to mark it
 140 .BR PROT_WRITE .
 141 .TP
 142 .B EINVAL
 143 \fIaddr\fP is not a valid pointer,
 144 or not a multiple of the system page size.
 145 .TP
 146 .BR EINVAL
 147 .RB ( pkey_mprotect ())
 148 \fIpkey\fP has not been allocated with
 149 .BR pkey_alloc (2)
 150 .TP
 151 .BR EINVAL
 152 Both
 153 .BR PROT_GROWSUP
 154 and
 155 .BR PROT_GROWSDOWN
 156 were specified in
 157 .IR prot .
 158 .TP
 159 .BR EINVAL
 160 Invalid flags specified in
 161 .IR prot .
 162 .TP
 163 .BR EINVAL
 164 (PowerPC architecture)
 165 .B PROT_SAO
 166 was specified in
 167 .IR prot ,
 168 but SAO hardware feature is not available.
 169 .TP
 170 .B ENOMEM
 171 Internal kernel structures could not be allocated.
 172 .TP
 173 .B ENOMEM
 174 Addresses in the range
 175 .RI [ addr ,
 176 .IR addr + len \-1]
 177 are invalid for the address space of the process,
 178 or specify one or more pages that are not mapped.
 179 (Before kernel 2.4.19, the error
 180 .BR EFAULT
 181 was incorrectly produced for these cases.)
 182 .TP
 183 .B ENOMEM
 184 Changing the protection of a memory region would result in the total number of
 185 mappings with distinct attributes (e.g., read versus read/write protection)
 186 exceeding the allowed maximum.
 187 .\" I.e., the number of VMAs would exceed the 64 kB maximum
 188 (For example, making the protection of a range
 189 .BR PROT_READ
 190 in the middle of a region currently protected as
 191 .BR PROT_READ|PROT_WRITE
 192 would result in three mappings:
 193 two read/write mappings at each end and a read-only mapping in the middle.)
 194 .SH VERSIONS
 195 .BR pkey_mprotect ()
 196 first appeared in Linux 4.9;
 197 library support was added in glibc 2.27.
 198 .SH CONFORMING TO
 199 .BR mprotect ():
 200 POSIX.1-2001, POSIX.1-2008, SVr4.
 201 .\" SVr4 defines an additional error
 202 .\" code EAGAIN. The SVr4 error conditions don't map neatly onto Linux's.
 203 POSIX says that the behavior of
 204 .BR mprotect ()
 205 is unspecified if it is applied to a region of memory that
 206 was not obtained via
 207 .BR mmap (2).
 208 .PP
 209 .BR pkey_mprotect ()
 210 is a nonportable Linux extension.
 211 .SH NOTES
 212 On Linux, it is always permissible to call
 213 .BR mprotect ()
 214 on any address in a process's address space (except for the
 215 kernel vsyscall area).
 216 In particular, it can be used
 217 to change existing code mappings to be writable.
 218 .PP
 219 Whether
 220 .B PROT_EXEC
 221 has any effect different from
 222 .B PROT_READ
 223 depends on processor architecture, kernel version, and process state.
 224 If
 225 .B READ_IMPLIES_EXEC
 226 is set in the process's personality flags (see
 227 .BR personality (2)),
 228 specifying
 229 .B PROT_READ
 230 will implicitly add
 231 .BR PROT_EXEC .
 232 .PP
 233 On some hardware architectures (e.g., i386),
 234 .B PROT_WRITE
 235 implies
 236 .BR PROT_READ .
 237 .PP
 238 POSIX.1 says that an implementation may permit access
 239 other than that specified in
 240 .IR prot ,
 241 but at a minimum can allow write access only if
 242 .B PROT_WRITE
 243 has been set, and must not allow any access if
 244 .B PROT_NONE
 245 has been set.
 246 .PP
 247 Applications should be careful when mixing use of
 248 .BR mprotect ()
 249 and
 250 .BR pkey_mprotect ().
 251 On x86, when
 252 .BR mprotect ()
 253 is used with
 254 .IR prot
 255 set to
 256 .B PROT_EXEC
 257 a pkey may be allocated and set on the memory implicitly
 258 by the kernel, but only when the pkey was 0 previously.
 259 .PP
 260 On systems that do not support protection keys in hardware,
 261 .BR pkey_mprotect ()
 262 may still be used, but
 263 .IR pkey
 264 must be set to \-1.
 265 When called this way, the operation of
 266 .BR pkey_mprotect ()
 267 is equivalent to
 268 .BR mprotect ().
 269 .SH EXAMPLES
 270 .\" sigaction.2 refers to this example
 271 The program below demonstrates the use of
 272 .BR mprotect ().
 273 The program allocates four pages of memory, makes the third
 274 of these pages read-only, and then executes a loop that walks upward
 275 through the allocated region modifying bytes.
 276 .PP
 277 An example of what we might see when running the program is the
 278 following:
 279 .PP
 280 .in +4n
 281 .EX
 282 .RB "$" " ./a.out"
 283 Start of region:        0x804c000
 284 Got SIGSEGV at address: 0x804e000
 285 .EE
 286 .in
 287 .SS Program source
 288 \&
 289 .EX
 290 #include <unistd.h>
 291 #include <signal.h>
 292 #include <stdio.h>
 293 #include <malloc.h>
 294 #include <stdlib.h>
 295 #include <errno.h>
 296 #include <sys/mman.h>
 297
 298 #define handle_error(msg) \e
 299     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 300
 301 static char *buffer;
 302
 303 static void
 304 handler(int sig, siginfo_t *si, void *unused)
 305 {
 306     /* Note: calling printf() from a signal handler is not safe
 307        (and should not be done in production programs), since
 308        printf() is not async\-signal\-safe; see signal\-safety(7).
 309        Nevertheless, we use printf() here as a simple way of
 310        showing that the handler was called. */
 311
 312     printf("Got SIGSEGV at address: %p\en", si\->si_addr);
 313     exit(EXIT_FAILURE);
 314 }
 315
 316 int
 317 main(int argc, char *argv[])
 318 {
 319     int pagesize;
 320     struct sigaction sa;
 321
 322     sa.sa_flags = SA_SIGINFO;
 323     sigemptyset(&sa.sa_mask);
 324     sa.sa_sigaction = handler;
 325     if (sigaction(SIGSEGV, &sa, NULL) == \-1)
 326         handle_error("sigaction");
 327
 328     pagesize = sysconf(_SC_PAGE_SIZE);
 329     if (pagesize == \-1)
 330         handle_error("sysconf");
 331
 332     /* Allocate a buffer aligned on a page boundary;
 333        initial protection is PROT_READ | PROT_WRITE. */
 334
 335     buffer = memalign(pagesize, 4 * pagesize);
 336     if (buffer == NULL)
 337         handle_error("memalign");
 338
 339     printf("Start of region:        %p\en", buffer);
 340
 341     if (mprotect(buffer + pagesize * 2, pagesize,
 342                 PROT_READ) == \-1)
 343         handle_error("mprotect");
 344
 345     for (char *p = buffer ; ; )
 346         *(p++) = \(aqa\(aq;
 347
 348     printf("Loop completed\en");     /* Should never happen */
 349     exit(EXIT_SUCCESS);
 350 }
 351 .EE
 352 .SH SEE ALSO
 353 .BR mmap (2),
 354 .BR sysconf (3),
 355 .BR pkeys (7)