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 27, 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 Creates both a mapped region that grows downward on demand and an
 323 adjoining guard that both reserves address space for the mapped region
 324 to grow into and limits the mapped region's growth.
 325 Together, the mapped region and the guard occupy
 326 .Fa len
 327 bytes of the address space.
 328 The guard starts at the returned address, and the mapped region ends at
 329 the returned address plus
 330 .Fa len
 331 bytes.
 332 Upon access to the guard, the mapped region automatically grows in size,
 333 and the guard shrinks by an equal amount.
 334 Essentially, the boundary between the guard and the mapped region moves
 335 downward so that the access falls within the enlarged mapped region.
 336 However, the guard will never shrink to less than the number of pages
 337 specified by the sysctl
 338 .Dv security.bsd.stack_guard_page ,
 339 thereby ensuring that a gap for detecting stack overflow always exists
 340 between the downward growing mapped region and the closest mapped region
 341 beneath it.
 342 .Pp
 343 .Dv MAP_STACK
 344 implies
 345 .Dv MAP_ANON
 346 and
 347 .Fa offset
 348 of 0.
 349 The
 350 .Fa fd
 351 argument
 352 must be -1 and
 353 .Fa prot
 354 must include at least
 355 .Dv PROT_READ
 356 and
 357 .Dv PROT_WRITE .
 358 The size of the guard, in pages, is specified by sysctl
 359 .Dv security.bsd.stack_guard_page .
 360 .El
 361 .Pp
 362 The
 363 .Xr close 2
 364 system call does not unmap pages, see
 365 .Xr munmap 2
 366 for further information.
 367 .Sh NOTES
 368 Although this implementation does not impose any alignment restrictions on
 369 the
 370 .Fa offset
 371 argument, a portable program must only use page-aligned values.
 372 .Pp
 373 Large page mappings require that the pages backing an object be
 374 aligned in matching blocks in both the virtual address space and RAM.
 375 The system will automatically attempt to use large page mappings when
 376 mapping an object that is already backed by large pages in RAM by
 377 aligning the mapping request in the virtual address space to match the
 378 alignment of the large physical pages.
 379 The system may also use large page mappings when mapping portions of an
 380 object that are not yet backed by pages in RAM.
 381 The
 382 .Dv MAP_ALIGNED_SUPER
 383 flag is an optimization that will align the mapping request to the
 384 size of a large page similar to
 385 .Dv MAP_ALIGNED ,
 386 except that the system will override this alignment if an object already
 387 uses large pages so that the mapping will be consistent with the existing
 388 large pages.
 389 This flag is mostly useful for maximizing the use of large pages on the
 390 first mapping of objects that do not yet have pages present in RAM.
 391 .Sh RETURN VALUES
 392 Upon successful completion,
 393 .Fn mmap
 394 returns a pointer to the mapped region.
 395 Otherwise, a value of
 396 .Dv MAP_FAILED
 397 is returned and
 398 .Va errno
 399 is set to indicate the error.
 400 .Sh ERRORS
 401 The
 402 .Fn mmap
 403 system call
 404 will fail if:
 405 .Bl -tag -width Er
 406 .It Bq Er EACCES
 407 The flag
 408 .Dv PROT_READ
 409 was specified as part of the
 410 .Fa prot
 411 argument and
 412 .Fa fd
 413 was not open for reading.
 414 The flags
 415 .Dv MAP_SHARED
 416 and
 417 .Dv PROT_WRITE
 418 were specified as part of the
 419 .Fa flags
 420 and
 421 .Fa prot
 422 argument and
 423 .Fa fd
 424 was not open for writing.
 425 .It Bq Er EBADF
 426 The
 427 .Fa fd
 428 argument
 429 is not a valid open file descriptor.
 430 .It Bq Er EINVAL
 431 An invalid (negative) value was passed in the
 432 .Fa offset
 433 argument, when
 434 .Fa fd
 435 referenced a regular file or shared memory.
 436 .It Bq Er EINVAL
 437 An invalid value was passed in the
 438 .Fa prot
 439 argument.
 440 .It Bq Er EINVAL
 441 An undefined option was set in the
 442 .Fa flags
 443 argument.
 444 .It Bq Er EINVAL
 445 Both
 446 .Dv MAP_PRIVATE
 447 and
 448 .Dv MAP_SHARED
 449 were specified.
 450 .It Bq Er EINVAL
 451 None of
 452 .Dv MAP_ANON ,
 453 .Dv MAP_GUARD ,
 454 .Dv MAP_PRIVATE ,
 455 .Dv MAP_SHARED ,
 456 or
 457 .Dv MAP_STACK
 458 was specified.
 459 At least one of these flags must be included.
 460 .It Bq Er EINVAL
 461 .Dv MAP_STACK
 462 was specified and
 463 .Va len
 464 is less than or equal to the guard size.
 465 .It Bq Er EINVAL
 466 .Dv MAP_FIXED
 467 was specified and the
 468 .Fa addr
 469 argument was not page aligned, or part of the desired address space
 470 resides out of the valid address space for a user process.
 471 .It Bq Er EINVAL
 472 Both
 473 .Dv MAP_FIXED
 474 and
 475 .Dv MAP_32BIT
 476 were specified and part of the desired address space resides outside
 477 of the first 2GB of user address space.
 478 .It Bq Er EINVAL
 479 The
 480 .Fa len
 481 argument
 482 was equal to zero.
 483 .It Bq Er EINVAL
 484 .Dv MAP_ALIGNED
 485 was specified and the desired alignment was either larger than the
 486 virtual address size of the machine or smaller than a page.
 487 .It Bq Er EINVAL
 488 .Dv MAP_ANON
 489 was specified and the
 490 .Fa fd
 491 argument was not -1.
 492 .It Bq Er EINVAL
 493 .Dv MAP_ANON
 494 was specified and the
 495 .Fa offset
 496 argument was not 0.
 497 .It Bq Er EINVAL
 498 Both
 499 .Dv MAP_FIXED
 500 and
 501 .Dv MAP_EXCL
 502 were specified, but the requested region is already used by a mapping.
 503 .It Bq Er EINVAL
 504 .Dv MAP_EXCL
 505 was specified, but
 506 .Dv MAP_FIXED
 507 was not.
 508 .It Bq Er EINVAL
 509 .Dv MAP_GUARD
 510 was specified, but the
 511 .Fa offset
 512 argument was not zero, the
 513 .Fa fd
 514 argument was not -1, or the
 515 .Fa prot
 516 argument was not
 517 .Dv PROT_NONE .
 518 .It Bq Er EINVAL
 519 .Dv MAP_GUARD
 520 was specified together with one of the flags
 521 .Dv MAP_ANON ,
 522 .Dv MAP_PREFAULT ,
 523 .Dv MAP_PREFAULT_READ ,
 524 .Dv MAP_PRIVATE ,
 525 .Dv MAP_SHARED ,
 526 .Dv MAP_STACK .
 527 .It Bq Er ENODEV
 528 .Dv MAP_ANON
 529 has not been specified and
 530 .Fa fd
 531 did not reference a regular or character special file.
 532 .It Bq Er ENOMEM
 533 .Dv MAP_FIXED
 534 was specified and the
 535 .Fa addr
 536 argument was not available.
 537 .Dv MAP_ANON
 538 was specified and insufficient memory was available.
 539 .It Bq Er ENOTSUP
 540 The
 541 .Fa prot
 542 argument contains protections which are not a subset of the specified
 543 maximum protections.
 544 .El
 545 .Sh SEE ALSO
 546 .Xr madvise 2 ,
 547 .Xr mincore 2 ,
 548 .Xr minherit 2 ,
 549 .Xr mlock 2 ,
 550 .Xr mprotect 2 ,
 551 .Xr msync 2 ,
 552 .Xr munlock 2 ,
 553 .Xr munmap 2 ,
 554 .Xr getpagesize 3 ,
 555 .Xr getpagesizes 3
 556 .Sh HISTORY
 557 The
 558 .Nm
 559 system call was first documented in
 560 .Bx 4.2
 561 and implemented in
 562 .Bx 4.4 .
 563 .\" XXX: lots of missing history of FreeBSD additions.
 564 .Pp
 565 The
 566 .Dv PROT_MAX
 567 functionality was introduced in
 568 .Fx 13 .