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