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