bsd/man/man2/mmap.2

   1 .\" Copyright (c) 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)mmap.2      8.4 (Berkeley) 5/11/95
  29 .\" $FreeBSD: src/lib/libc/sys/mmap.2,v 1.56 2007/01/09 00:28:15 imp Exp $
  30 .\"
  31 .Dd February 14, 2020
  32 .Dt MMAP 2
  33 .Os
  34 .Sh NAME
  35 .Nm mmap
  36 .Nd allocate memory, or map files or devices into memory
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/mman.h
  41 .Ft void *
  42 .Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn mmap
  46 system call causes the pages starting at
  47 .Fa addr
  48 and continuing for at most
  49 .Fa len
  50 bytes to be mapped from the object described by
  51 .Fa fd ,
  52 starting at byte offset
  53 .Fa offset .
  54 If
  55 .Fa offset
  56 or
  57 .Fa len
  58 is not a multiple of the pagesize, the mapped region may extend past the
  59 specified range.
  60 Any extension beyond the end of the mapped object will be zero-filled.
  61 .Pp
  62 The
  63 .Fa addr
  64 argument is used by the system to determine the starting address of the mapping,
  65 and its interpretation is dependent on the setting of the MAP_FIXED flag.
  66 If MAP_FIXED is specified in
  67 .Fa flags ,
  68 the system will try to place the mapping at the specified address,
  69 possibly removing a
  70 mapping that already exists at that location.
  71 If MAP_FIXED is not specified,
  72 then the system will attempt to use the range of addresses starting at
  73 .Fa addr
  74 if they do not overlap any existing mappings,
  75 including memory allocated by
  76 .Xr malloc 3
  77 and other such allocators.
  78 Otherwise,
  79 the system will choose an alternate address for the mapping (using an implementation
  80 dependent algorithm)
  81 that does not overlap any existing
  82 mappings.
  83 In other words,
  84 without
  85 .Dv MAP_FIXED
  86 the system will attempt to find an empty location in the address space if the
  87 specified address range has already been mapped by something else.
  88 If
  89 .Fa addr
  90 is zero and MAP_FIXED is not specified,
  91 then an address will be selected by the system so as not to overlap
  92 any existing mappings in the address space.
  93 In all cases,
  94 the actual starting address of the region is returned.
  95 If MAP_FIXED is specified,
  96 a successful
  97 .Fa mmap
  98 deletes any previous mapping in the allocated address range.
  99 Previous mappings are never deleted if MAP_FIXED is not specified.
 100 .Pp
 101 The protections (region accessibility) are specified in the
 102 .Fa prot
 103 argument by
 104 .Em or Ns 'ing
 105 the following values:
 106 .Pp
 107 .Bl -tag -width PROT_WRITE -compact
 108 .It Dv PROT_NONE
 109 Pages may not be accessed.
 110 .It Dv PROT_READ
 111 Pages may be read.
 112 .It Dv PROT_WRITE
 113 Pages may be written.
 114 .It Dv PROT_EXEC
 115 Pages may be executed.
 116 .El
 117 .Pp
 118 Note that, due to hardware limitations, on some platforms PROT_WRITE may
 119 imply PROT_READ, and PROT_READ may imply PROT_EXEC.  Portable programs
 120 should not rely on these flags being separately enforceable.
 121 .Pp
 122 When the hardened runtime is enabled
 123 .Po
 124 See the links in the
 125 .Sx SEE ALSO
 126 section
 127 .Pc ,
 128 the protections cannot be both
 129 .Dv PROT_WRITE
 130 and
 131 .Dv PROT_EXEC
 132 without also having the flag
 133 .Dv MAP_JIT
 134 and the process possessing the
 135 .Dv com.apple.security.cs.allow-jit
 136 entitlement
 137 .Pp
 138 The
 139 .Fa flags
 140 argument specifies the type of the mapped object, mapping options and
 141 whether modifications made to the mapped copy of the page are private
 142 to the process (copy-on-write) or are to be shared with other references.
 143 Sharing, mapping type and options are specified in the
 144 .Fa flags
 145 argument by
 146 .Em or Ns 'ing
 147 the following values:
 148 .Bl -tag -width MAP_HASSEMAPHORE
 149 .It Dv MAP_ANONYMOUS
 150 Synonym for
 151 .Dv MAP_ANON.
 152 .It Dv MAP_ANON
 153 Map anonymous memory not associated with any specific file.
 154 The
 155 .Fa offset
 156 argument is ignored.
 157 Mac OS X specific: the file descriptor used for creating
 158 .Dv MAP_ANON
 159 regions can be used to pass some Mach VM flags, and can
 160 be specified as \-1 if no such flags are associated with
 161 the region.  Mach VM flags are defined in
 162 .In mach/vm_statistics.h
 163 and the ones that currently apply
 164 to
 165 .Nm mmap
 166 are:
 167 .Pp
 168 VM_FLAGS_PURGABLE       to create Mach purgable (i.e. volatile) memory.
 169 .Pp
 170 VM_MAKE_TAG(tag)        to associate an 8-bit tag with the region.
 171 .br
 172 .In mach/vm_statistics.h
 173 defines some preset tags (with a VM_MEMORY_ prefix).
 174 Users are encouraged to use tags between 240 and 255.
 175 Tags are used by tools such as
 176 .Xr vmmap 1
 177 to help identify specific memory regions.
 178 .It Dv MAP_FILE
 179 Mapped from a regular file.  (This is
 180 the default mapping type, and need not be specified.)
 181 .It Dv MAP_FIXED
 182 Do not permit the system to select a different address than the one
 183 specified.
 184 If the specified address cannot be used,
 185 .Fn mmap
 186 will fail.
 187 If
 188 .Dv MAP_FIXED
 189 is specified,
 190 .Fa addr
 191 must be a multiple of the pagesize.
 192 If a
 193 .Dv MAP_FIXED
 194 request is successful, the mapping established by
 195 .Fn mmap
 196 replaces any previous mappings for the process' pages in the range from
 197 .Fa addr
 198 to
 199 .Fa addr
 200 +
 201 .Fa len .
 202 Use of this option is discouraged.
 203 .It Dv MAP_HASSEMAPHORE
 204 Notify the kernel that the region may contain semaphores and that special
 205 handling may be necessary.
 206 .It Dv MAP_PRIVATE
 207 Modifications are private (copy-on-write).
 208 .It Dv MAP_SHARED
 209 Modifications are shared.
 210 .It Dv MAP_NOCACHE
 211 Pages in this mapping are not retained in the kernel's memory cache.
 212 If the system runs low on memory, pages in MAP_NOCACHE mappings will be among
 213 the first to be reclaimed.
 214 This flag is intended for mappings that have little locality and
 215 provides a hint to the kernel that pages in this mapping are unlikely to be needed
 216 again in the near future.
 217 .It Dv MAP_JIT
 218 Allow mapping pages both
 219 .Dv PROT_WRITE
 220 and
 221 .Dv PROT_EXEC
 222 when the hardened is runtime enabled. Without this flag an attempt to create a
 223 mapping with both
 224 .Dv PROT_WRITE
 225 and
 226 .Dv PROT_EXEC
 227 set will fail with
 228 .Dv MAP_FAILED
 229 on macOS. A writable, but not executable mapping
 230 is returned on iOS, watchOS and tvOS.
 231 .Pp
 232 Usage of this flag requires the caller to have the
 233 .Dv com.apple.security.cs.allow-jit
 234 entitlement on macOS.
 235 .It Dv MAP_32BIT
 236 Directs
 237 .Fn mmap
 238 to place the mapping into the first 4 Gigabytes of the process's address space.  If
 239 there is no free virtual address space in this range,
 240 .Fn mmap
 241 will return
 242 .Dv MAP_FAILED.
 243 .Pp
 244 Note that in order for this flag to yield addresses below 4GiB, the program's
 245 PAGEZERO must be reduced in size, since the default PAGEZERO size for 64-bit
 246 programs is at least 4GiB.
 247 .El
 248 .Pp
 249 Conforming applications must specify either MAP_PRIVATE or MAP_SHARED.
 250 .Pp
 251 The
 252 .Xr close 2
 253 system call does not unmap pages, see
 254 .Xr munmap 2
 255 for further information.
 256 .Pp
 257 The current design does not allow a process to specify the location of
 258 swap space.
 259 In the future we may define an additional mapping type,
 260 .Dv MAP_SWAP ,
 261 in which
 262 the file descriptor argument specifies a file or device to which swapping
 263 should be done.
 264 .Sh RETURN VALUES
 265 Upon successful completion,
 266 .Fn mmap
 267 returns a pointer to the mapped region.
 268 Otherwise, a value of
 269 .Dv MAP_FAILED
 270 is returned and
 271 .Va errno
 272 is set to indicate the error.
 273 .Sh ERRORS
 274 The
 275 .Fn mmap
 276 system call
 277 will fail if:
 278 .Bl -tag -width Er
 279 .It Bq Er EACCES
 280 The flag
 281 .Dv PROT_READ
 282 was specified as part of the
 283 .Fa prot
 284 argument and
 285 .Fa fd
 286 was not open for reading.
 287 The flags
 288 .Dv MAP_SHARED
 289 and
 290 .Dv PROT_WRITE
 291 were specified as part of the
 292 .Fa flags
 293 and
 294 .Fa prot
 295 argument and
 296 .Fa fd
 297 was not open for writing.
 298 .It Bq Er EBADF
 299 The
 300 .Fa fd
 301 argument
 302 is not a valid open file descriptor.
 303 .It Bq Er EINVAL
 304 .Dv MAP_FIXED
 305 was specified and the
 306 .Fa addr
 307 argument was not page aligned, or part of the desired address space
 308 resides out of the valid address space for a user process.
 309 .It Bq Er EINVAL
 310 .Fa flags
 311 does not include either MAP_PRIVATE or MAP_SHARED.
 312 .It Bq Er EINVAL
 313 .Fa flags
 314 includes bits that are not part of any valid flags value.
 315 .It Bq Er EINVAL
 316 The
 317 .Fa len
 318 argument
 319 was negative or zero. Historically, the system call would not return an error
 320 if the argument was zero.
 321 See other potential additional restrictions in the
 322 COMPATIBILITY section below.
 323 .It Bq Er EINVAL
 324 The
 325 .Fa offset
 326 argument
 327 was not page-aligned based on the page size as returned by getpagesize(3).
 328 .It Bq Er ENODEV
 329 .Dv MAP_ANON
 330 has not been specified and the file
 331 .Fa fd
 332 refers to does not support mapping.
 333 .It Bq Er ENOMEM
 334 .Dv MAP_FIXED
 335 was specified and the
 336 .Fa addr
 337 argument was not available.
 338 .Dv MAP_FIXED
 339 was specified and the address range specified exceeds the address space
 340 limit for the process.
 341 .Dv MAP_ANON
 342 was specified and insufficient memory was available.
 343 .It Bq Er ENXIO
 344 Addresses in the specified range are invalid for
 345 .Fa fd .
 346 .It Bq Er EOVERFLOW
 347 Addresses in the specified range exceed the maximum offset
 348 set for
 349 .Fa fd .
 350 .El
 351 .Sh ENTITLEMENTS
 352 The following entitlements only have an effect when the hardened runtime is
 353 enabled.
 354 .Bl -tag -width Er
 355 .It Dv com.apple.security.cs.allow-jit
 356 A Boolean value that indicates whether the app may create writable and
 357 executable memory using the
 358 .Dv MAP_JIT
 359 .Fa flag .
 360 .It Dv com.apple.security.cs.allow-unsigned-executable-memory
 361 A Boolean value that indicates whether the app may create writable and
 362 executable memory without the restrictions imposed by using the
 363 .Dv MAP_JIT
 364 .Fa flag .
 365 .It Dv com.apple.security.cs.disable-executable-page-protection
 366 A Boolean value that indicates whether to disable all code signing
 367 protections while launching an application, and during its execution.
 368 .El
 369 .Sh LEGACY SYNOPSIS
 370 .Fd #include <sys/types.h>
 371 .Fd #include <sys/mman.h>
 372 .Pp
 373 The include file
 374 .In sys/types.h
 375 is necessary.
 376 .Sh COMPATIBILITY
 377 .Fn mmap
 378 now returns with
 379 .Va errno
 380 set to EINVAL in places that historically succeeded.
 381 The rules have changed as follows:
 382 .Bl -bullet
 383 .It
 384 The
 385 .Fa flags
 386 parameter must specify either MAP_PRIVATE or MAP_SHARED.
 387 .It
 388 The
 389 .Fa len
 390 parameter must not be 0.
 391 .It
 392 The
 393 .Fa off
 394 parameter must be a multiple of pagesize,
 395 as returned by
 396 .Fn sysconf .
 397 .El
 398 .Pp
 399 On macOS 10.14 Mojave the hardened runtime restricts pages from having both
 400 the
 401 .Dv PROT_WRITE
 402 and
 403 .Dv PROT_EXEC
 404 protections without the caller also setting the
 405 .Dv MAP_JIT
 406 .Fa flag
 407 and possessing the
 408 .Dv com.apple.security.cs.allow-jit
 409 entitlement.
 410 .Sh SEE ALSO
 411 .Xr madvise 2 ,
 412 .Xr mincore 2 ,
 413 .Xr minherit 2 ,
 414 .Xr mlock 2 ,
 415 .Xr mprotect 2 ,
 416 .Xr msync 2 ,
 417 .Xr munlock 2 ,
 418 .Xr munmap 2 ,
 419 .Xr shmat 2 ,
 420 .Xr getpagesize 3
 421 .Ss Apple Developer Documentation
 422 https://developer.apple.com/documentation/security/hardened_runtime_entitlements