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