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