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