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