lib/libc/sys/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 .\" 3. 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$
  30 .\"
  31 .Dd October 21, 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 len
  56 is not a multiple of the page size, the mapped region may extend past the
  57 specified range.
  58 Any such extension beyond the end of the mapped object will be zero-filled.
  59 .Pp
  60 If
  61 .Fa fd
  62 references a regular file or a shared memory object, the range of
  63 bytes starting at
  64 .Fa offset
  65 and continuing for
  66 .Fa len
  67 bytes must be legitimate for the possible (not necessarily
  68 current) offsets in the object.
  69 In particular, the
  70 .Fa offset
  71 value cannot be negative.
  72 If the object is truncated and the process later accesses a page that
  73 is wholly within the truncated region, the access is aborted and a
  74 .Dv SIGBUS
  75 signal is delivered to the process.
  76 .Pp
  77 If
  78 .Fa fd
  79 references a device file, the interpretation of the
  80 .Fa offset
  81 value is device specific and defined by the device driver.
  82 The virtual memory subsystem does not impose any restrictitions on the
  83 .Fa offset
  84 value in this case, passing it unchanged to the driver.
  85 .Pp
  86 If
  87 .Fa addr
  88 is non-zero, it is used as a hint to the system.
  89 (As a convenience to the system, the actual address of the region may differ
  90 from the address supplied.)
  91 If
  92 .Fa addr
  93 is zero, an address will be selected by the system.
  94 The actual starting address of the region is returned.
  95 A successful
  96 .Fa mmap
  97 deletes any previous mapping in the allocated address range.
  98 .Pp
  99 The protections (region accessibility) are specified in the
 100 .Fa prot
 101 argument by
 102 .Em or Ns 'ing
 103 the following values:
 104 .Pp
 105 .Bl -tag -width PROT_WRITE -compact
 106 .It Dv PROT_NONE
 107 Pages may not be accessed.
 108 .It Dv PROT_READ
 109 Pages may be read.
 110 .It Dv PROT_WRITE
 111 Pages may be written.
 112 .It Dv PROT_EXEC
 113 Pages may be executed.
 114 .El
 115 .Pp
 116 In addition to these protection flags,
 117 .Fx
 118 provides the ability to set the maximum protection of a region allocated by
 119 .Nm
 120 and later altered by
 121 .Xr mprotect 2 .
 122 This is accomplished by
 123 .Em or Ns 'ing
 124 one or more
 125 .Dv PROT_
 126 values wrapped in the
 127 .Dv PROT_MAX()
 128 macro into the
 129 .Fa prot
 130 argument.
 131 .Pp
 132 The
 133 .Fa flags
 134 argument specifies the type of the mapped object, mapping options and
 135 whether modifications made to the mapped copy of the page are private
 136 to the process or are to be shared with other references.
 137 Sharing, mapping type and options are specified in the
 138 .Fa flags
 139 argument by
 140 .Em or Ns 'ing
 141 the following values:
 142 .Bl -tag -width MAP_PREFAULT_READ
 143 .It Dv MAP_32BIT
 144 Request a region in the first 2GB of the current process's address space.
 145 If a suitable region cannot be found,
 146 .Fn mmap
 147 will fail.
 148 This flag is only available on 64-bit platforms.
 149 .It Dv MAP_ALIGNED Ns Pq Fa n
 150 Align the region on a requested boundary.
 151 If a suitable region cannot be found,
 152 .Fn mmap
 153 will fail.
 154 The
 155 .Fa n
 156 argument specifies the binary logarithm of the desired alignment.
 157 .It Dv MAP_ALIGNED_SUPER
 158 Align the region to maximize the potential use of large
 159 .Pq Dq super
 160 pages.
 161 If a suitable region cannot be found,
 162 .Fn mmap
 163 will fail.
 164 The system will choose a suitable page size based on the size of
 165 mapping.
 166 The page size used as well as the alignment of the region may both be
 167 affected by properties of the file being mapped.
 168 In particular,
 169 the physical address of existing pages of a file may require a specific
 170 alignment.
 171 The region is not guaranteed to be aligned on any specific boundary.
 172 .It Dv MAP_ANON
 173 Map anonymous memory not associated with any specific file.
 174 The file descriptor used for creating
 175 .Dv MAP_ANON
 176 must be \-1.
 177 The
 178 .Fa offset
 179 argument must be 0.
 180 .\".It Dv MAP_FILE
 181 .\"Mapped from a regular file or character-special device memory.
 182 .It Dv MAP_ANONYMOUS
 183 This flag is identical to
 184 .Dv MAP_ANON
 185 and is provided for compatibility.
 186 .It Dv MAP_EXCL
 187 This flag can only be used in combination with
 188 .Dv MAP_FIXED .
 189 Please see the definition of
 190 .Dv MAP_FIXED
 191 for the description of its effect.
 192 .It Dv MAP_FIXED
 193 Do not permit the system to select a different address than the one
 194 specified.
 195 If the specified address cannot be used,
 196 .Fn mmap
 197 will fail.
 198 If
 199 .Dv MAP_FIXED
 200 is specified,
 201 .Fa addr
 202 must be a multiple of the page size.
 203 If
 204 .Dv MAP_EXCL
 205 is not specified, a successful
 206 .Dv MAP_FIXED
 207 request replaces any previous mappings for the process'
 208 pages in the range from
 209 .Fa addr
 210 to
 211 .Fa addr
 212 +
 213 .Fa len .
 214 In contrast, if
 215 .Dv MAP_EXCL
 216 is specified, the request will fail if a mapping
 217 already exists within the range.
 218 .It Dv MAP_GUARD
 219 Instead of a mapping, create a guard of the specified size.
 220 Guards allow a process to create reservations in its address space,
 221 which can later be replaced by actual mappings.
 222 .Pp
 223 .Fa mmap
 224 will not create mappings in the address range of a guard unless
 225 the request specifies
 226 .Dv MAP_FIXED .
 227 Guards can be destroyed with
 228 .Xr munmap 2 .
 229 Any memory access by a thread to the guarded range results
 230 in the delivery of a
 231 .Dv SIGSEGV
 232 signal to that thread.
 233 .It Dv MAP_NOCORE
 234 Region is not included in a core file.
 235 .It Dv MAP_NOSYNC
 236 Causes data dirtied via this VM map to be flushed to physical media
 237 only when necessary (usually by the pager) rather than gratuitously.
 238 Typically this prevents the update daemons from flushing pages dirtied
 239 through such maps and thus allows efficient sharing of memory across
 240 unassociated processes using a file-backed shared memory map.
 241 Without
 242 this option any VM pages you dirty may be flushed to disk every so often
 243 (every 30-60 seconds usually) which can create performance problems if you
 244 do not need that to occur (such as when you are using shared file-backed
 245 mmap regions for IPC purposes).
 246 Dirty data will be flushed automatically when all mappings of an object are
 247 removed and all descriptors referencing the object are closed.
 248 Note that VM/file system coherency is
 249 maintained whether you use
 250 .Dv MAP_NOSYNC
 251 or not.
 252 This option is not portable
 253 across
 254 .Ux
 255 platforms (yet), though some may implement the same behavior
 256 by default.
 257 .Pp
 258 .Em WARNING !
 259 Extending a file with
 260 .Xr ftruncate 2 ,
 261 thus creating a big hole, and then filling the hole by modifying a shared
 262 .Fn mmap
 263 can lead to severe file fragmentation.
 264 In order to avoid such fragmentation you should always pre-allocate the
 265 file's backing store by
 266 .Fn write Ns ing
 267 zero's into the newly extended area prior to modifying the area via your
 268 .Fn mmap .
 269 The fragmentation problem is especially sensitive to
 270 .Dv MAP_NOSYNC
 271 pages, because pages may be flushed to disk in a totally random order.
 272 .Pp
 273 The same applies when using
 274 .Dv MAP_NOSYNC
 275 to implement a file-based shared memory store.
 276 It is recommended that you create the backing store by
 277 .Fn write Ns ing
 278 zero's to the backing file rather than
 279 .Fn ftruncate Ns ing
 280 it.
 281 You can test file fragmentation by observing the KB/t (kilobytes per
 282 transfer) results from an
 283 .Dq Li iostat 1
 284 while reading a large file sequentially, e.g.,\& using
 285 .Dq Li dd if=filename of=/dev/null bs=32k .
 286 .Pp
 287 The
 288 .Xr fsync 2
 289 system call will flush all dirty data and metadata associated with a file,
 290 including dirty NOSYNC VM data, to physical media.
 291 The
 292 .Xr sync 8
 293 command and
 294 .Xr sync 2
 295 system call generally do not flush dirty NOSYNC VM data.
 296 The
 297 .Xr msync 2
 298 system call is usually not needed since
 299 .Bx
 300 implements a coherent file system buffer cache.
 301 However, it may be
 302 used to associate dirty VM pages with file system buffers and thus cause
 303 them to be flushed to physical media sooner rather than later.
 304 .It Dv MAP_PREFAULT_READ
 305 Immediately update the calling process's lowest-level virtual address
 306 translation structures, such as its page table, so that every memory
 307 resident page within the region is mapped for read access.
 308 Ordinarily these structures are updated lazily.
 309 The effect of this option is to eliminate any soft faults that would
 310 otherwise occur on the initial read accesses to the region.
 311 Although this option does not preclude
 312 .Fa prot
 313 from including
 314 .Dv PROT_WRITE ,
 315 it does not eliminate soft faults on the initial write accesses to the
 316 region.
 317 .It Dv MAP_PRIVATE
 318 Modifications are private.
 319 .It Dv MAP_SHARED
 320 Modifications are shared.
 321 .It Dv MAP_STACK
 322 .Dv MAP_STACK
 323 implies
 324 .Dv MAP_ANON ,
 325 and
 326 .Fa offset
 327 of 0.
 328 The
 329 .Fa fd
 330 argument
 331 must be -1 and
 332 .Fa prot
 333 must include at least
 334 .Dv PROT_READ
 335 and
 336 .Dv PROT_WRITE .
 337 .Pp
 338 This option creates
 339 a memory region that grows to at most
 340 .Fa len
 341 bytes in size, starting from the stack top and growing down.
 342 The
 343 stack top is the starting address returned by the call, plus
 344 .Fa len
 345 bytes.
 346 The bottom of the stack at maximum growth is the starting
 347 address returned by the call.
 348 .Pp
 349 Stacks created with
 350 .Dv MAP_STACK
 351 automatically grow.
 352 Guards prevent inadvertent use of the regions into which those
 353 stacks can grow without requiring mapping the whole stack in advance.
 354 The size of the guard, in pages, is specified by sysctl
 355 .Dv security.bsd.stack_guard_page .
 356 .El
 357 .Pp
 358 The
 359 .Xr close 2
 360 system call does not unmap pages, see
 361 .Xr munmap 2
 362 for further information.
 363 .Sh NOTES
 364 Although this implementation does not impose any alignment restrictions on
 365 the
 366 .Fa offset
 367 argument, a portable program must only use page-aligned values.
 368 .Pp
 369 Large page mappings require that the pages backing an object be
 370 aligned in matching blocks in both the virtual address space and RAM.
 371 The system will automatically attempt to use large page mappings when
 372 mapping an object that is already backed by large pages in RAM by
 373 aligning the mapping request in the virtual address space to match the
 374 alignment of the large physical pages.
 375 The system may also use large page mappings when mapping portions of an
 376 object that are not yet backed by pages in RAM.
 377 The
 378 .Dv MAP_ALIGNED_SUPER
 379 flag is an optimization that will align the mapping request to the
 380 size of a large page similar to
 381 .Dv MAP_ALIGNED ,
 382 except that the system will override this alignment if an object already
 383 uses large pages so that the mapping will be consistent with the existing
 384 large pages.
 385 This flag is mostly useful for maximizing the use of large pages on the
 386 first mapping of objects that do not yet have pages present in RAM.
 387 .Sh RETURN VALUES
 388 Upon successful completion,
 389 .Fn mmap
 390 returns a pointer to the mapped region.
 391 Otherwise, a value of
 392 .Dv MAP_FAILED
 393 is returned and
 394 .Va errno
 395 is set to indicate the error.
 396 .Sh ERRORS
 397 The
 398 .Fn mmap
 399 system call
 400 will fail if:
 401 .Bl -tag -width Er
 402 .It Bq Er EACCES
 403 The flag
 404 .Dv PROT_READ
 405 was specified as part of the
 406 .Fa prot
 407 argument and
 408 .Fa fd
 409 was not open for reading.
 410 The flags
 411 .Dv MAP_SHARED
 412 and
 413 .Dv PROT_WRITE
 414 were specified as part of the
 415 .Fa flags
 416 and
 417 .Fa prot
 418 argument and
 419 .Fa fd
 420 was not open for writing.
 421 .It Bq Er EBADF
 422 The
 423 .Fa fd
 424 argument
 425 is not a valid open file descriptor.
 426 .It Bq Er EINVAL
 427 An invalid (negative) value was passed in the
 428 .Fa offset
 429 argument, when
 430 .Fa fd
 431 referenced a regular file or shared memory.
 432 .It Bq Er EINVAL
 433 An invalid value was passed in the
 434 .Fa prot
 435 argument.
 436 .It Bq Er EINVAL
 437 An undefined option was set in the
 438 .Fa flags
 439 argument.
 440 .It Bq Er EINVAL
 441 Both
 442 .Dv MAP_PRIVATE
 443 and
 444 .Dv MAP_SHARED
 445 were specified.
 446 .It Bq Er EINVAL
 447 None of
 448 .Dv MAP_ANON ,
 449 .Dv MAP_GUARD ,
 450 .Dv MAP_PRIVATE ,
 451 .Dv MAP_SHARED ,
 452 or
 453 .Dv MAP_STACK
 454 was specified.
 455 At least one of these flags must be included.
 456 .It Bq Er EINVAL
 457 .Dv MAP_STACK
 458 was specified and
 459 .Va len
 460 is less than or equal to the guard size.
 461 .It Bq Er EINVAL
 462 .Dv MAP_FIXED
 463 was specified and the
 464 .Fa addr
 465 argument was not page aligned, or part of the desired address space
 466 resides out of the valid address space for a user process.
 467 .It Bq Er EINVAL
 468 Both
 469 .Dv MAP_FIXED
 470 and
 471 .Dv MAP_32BIT
 472 were specified and part of the desired address space resides outside
 473 of the first 2GB of user address space.
 474 .It Bq Er EINVAL
 475 The
 476 .Fa len
 477 argument
 478 was equal to zero.
 479 .It Bq Er EINVAL
 480 .Dv MAP_ALIGNED
 481 was specified and the desired alignment was either larger than the
 482 virtual address size of the machine or smaller than a page.
 483 .It Bq Er EINVAL
 484 .Dv MAP_ANON
 485 was specified and the
 486 .Fa fd
 487 argument was not -1.
 488 .It Bq Er EINVAL
 489 .Dv MAP_ANON
 490 was specified and the
 491 .Fa offset
 492 argument was not 0.
 493 .It Bq Er EINVAL
 494 Both
 495 .Dv MAP_FIXED
 496 and
 497 .Dv MAP_EXCL
 498 were specified, but the requested region is already used by a mapping.
 499 .It Bq Er EINVAL
 500 .Dv MAP_EXCL
 501 was specified, but
 502 .Dv MAP_FIXED
 503 was not.
 504 .It Bq Er EINVAL
 505 .Dv MAP_GUARD
 506 was specified, but the
 507 .Fa offset
 508 argument was not zero, the
 509 .Fa fd
 510 argument was not -1, or the
 511 .Fa prot
 512 argument was not
 513 .Dv PROT_NONE .
 514 .It Bq Er EINVAL
 515 .Dv MAP_GUARD
 516 was specified together with one of the flags
 517 .Dv MAP_ANON ,
 518 .Dv MAP_PREFAULT ,
 519 .Dv MAP_PREFAULT_READ ,
 520 .Dv MAP_PRIVATE ,
 521 .Dv MAP_SHARED ,
 522 .Dv MAP_STACK .
 523 .It Bq Er ENODEV
 524 .Dv MAP_ANON
 525 has not been specified and
 526 .Fa fd
 527 did not reference a regular or character special file.
 528 .It Bq Er ENOMEM
 529 .Dv MAP_FIXED
 530 was specified and the
 531 .Fa addr
 532 argument was not available.
 533 .Dv MAP_ANON
 534 was specified and insufficient memory was available.
 535 .It Bq Er ENOTSUP
 536 The
 537 .Fa prot
 538 argument contains protections which are not a subset of the specified
 539 maximum protections.
 540 .El
 541 .Sh SEE ALSO
 542 .Xr madvise 2 ,
 543 .Xr mincore 2 ,
 544 .Xr minherit 2 ,
 545 .Xr mlock 2 ,
 546 .Xr mprotect 2 ,
 547 .Xr msync 2 ,
 548 .Xr munlock 2 ,
 549 .Xr munmap 2 ,
 550 .Xr getpagesize 3 ,
 551 .Xr getpagesizes 3
 552 .Sh HISTORY
 553 The
 554 .Nm
 555 system call was first documented in
 556 .Bx 4.2
 557 and implemented in
 558 .Bx 4.4 .
 559 .\" XXX: lots of missing history of FreeBSD additions.
 560 .Pp
 561 The
 562 .Dv PROT_MAX
 563 functionality was introduced in
 564 .Fx 13 .