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