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 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)mmap.2      8.4 (Berkeley) 5/11/95
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd November 17, 2001
  36 .Dt MMAP 2
  37 .Os
  38 .Sh NAME
  39 .Nm mmap
  40 .Nd allocate memory, or map files or devices into memory
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/mman.h
  45 .Ft void *
  46 .Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn mmap
  50 system call causes the pages starting at
  51 .Fa addr
  52 and continuing for at most
  53 .Fa len
  54 bytes to be mapped from the object described by
  55 .Fa fd ,
  56 starting at byte offset
  57 .Fa offset .
  58 If
  59 .Fa len
  60 is not a multiple of the pagesize, the mapped region may extend past the
  61 specified range.
  62 Any such extension beyond the end of the mapped object will be zero-filled.
  63 .Pp
  64 If
  65 .Fa addr
  66 is non-zero, it is used as a hint to the system.
  67 (As a convenience to the system, the actual address of the region may differ
  68 from the address supplied.)
  69 If
  70 .Fa addr
  71 is zero, an address will be selected by the system.
  72 The actual starting address of the region is returned.
  73 A successful
  74 .Fa mmap
  75 deletes any previous mapping in the allocated address range.
  76 .Pp
  77 The protections (region accessibility) are specified in the
  78 .Fa prot
  79 argument by
  80 .Em or Ns 'ing
  81 the following values:
  82 .Pp
  83 .Bl -tag -width PROT_WRITE -compact
  84 .It Dv PROT_NONE
  85 Pages may not be accessed.
  86 .It Dv PROT_READ
  87 Pages may be read.
  88 .It Dv PROT_WRITE
  89 Pages may be written.
  90 .It Dv PROT_EXEC
  91 Pages may be executed.
  92 .El
  93 .Pp
  94 The
  95 .Fa flags
  96 argument specifies the type of the mapped object, mapping options and
  97 whether modifications made to the mapped copy of the page are private
  98 to the process or are to be shared with other references.
  99 Sharing, mapping type and options are specified in the
 100 .Fa flags
 101 argument by
 102 .Em or Ns 'ing
 103 the following values:
 104 .Bl -tag -width MAP_HASSEMAPHORE
 105 .It Dv MAP_ANON
 106 Map anonymous memory not associated with any specific file.
 107 The file descriptor used for creating
 108 .Dv MAP_ANON
 109 must be \-1.
 110 The
 111 .Fa offset
 112 argument is ignored.
 113 .\".It Dv MAP_FILE
 114 .\"Mapped from a regular file or character-special device memory.
 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 Use of this option is discouraged.
 127 .It Dv MAP_HASSEMAPHORE
 128 Notify the kernel that the region may contain semaphores and that special
 129 handling may be necessary.
 130 .It Dv MAP_INHERIT
 131 This flag never operated as advertised and is no longer supported.
 132 Please refer to
 133 .Xr minherit 2
 134 for further information.
 135 .It Dv MAP_NOCORE
 136 Region is not included in a core file.
 137 .It Dv MAP_NOSYNC
 138 Causes data dirtied via this VM map to be flushed to physical media
 139 only when necessary (usually by the pager) rather than gratuitously.
 140 Typically this prevents the update daemons from flushing pages dirtied
 141 through such maps and thus allows efficient sharing of memory across
 142 unassociated processes using a file-backed shared memory map.
 143 Without
 144 this option any VM pages you dirty may be flushed to disk every so often
 145 (every 30-60 seconds usually) which can create performance problems if you
 146 do not need that to occur (such as when you are using shared file-backed
 147 mmap regions for IPC purposes).
 148 Note that VM/file system coherency is
 149 maintained whether you use
 150 .Dv MAP_NOSYNC
 151 or not.
 152 This option is not portable
 153 across
 154 .Ux
 155 platforms (yet), though some may implement the same behavior
 156 by default.
 157 .Pp
 158 .Em WARNING !
 159 Extending a file with
 160 .Xr ftruncate 2 ,
 161 thus creating a big hole, and then filling the hole by modifying a shared
 162 .Fn mmap
 163 can lead to severe file fragmentation.
 164 In order to avoid such fragmentation you should always pre-allocate the
 165 file's backing store by
 166 .Fn write Ns ing
 167 zero's into the newly extended area prior to modifying the area via your
 168 .Fn mmap .
 169 The fragmentation problem is especially sensitive to
 170 .Dv MAP_NOSYNC
 171 pages, because pages may be flushed to disk in a totally random order.
 172 .Pp
 173 The same applies when using
 174 .Dv MAP_NOSYNC
 175 to implement a file-based shared memory store.
 176 It is recommended that you create the backing store by
 177 .Fn write Ns ing
 178 zero's to the backing file rather than
 179 .Fn ftruncate Ns ing
 180 it.
 181 You can test file fragmentation by observing the KB/t (kilobytes per
 182 transfer) results from an
 183 .Dq Li iostat 1
 184 while reading a large file sequentially, e.g.\& using
 185 .Dq Li dd if=filename of=/dev/null bs=32k .
 186 .Pp
 187 The
 188 .Xr fsync 2
 189 system call will flush all dirty data and metadata associated with a file,
 190 including dirty NOSYNC VM data, to physical media.
 191 The
 192 .Xr sync 8
 193 command and
 194 .Xr sync 2
 195 system call generally do not flush dirty NOSYNC VM data.
 196 The
 197 .Xr msync 2
 198 system call is obsolete since
 199 .Bx
 200 implements a coherent file system buffer cache.
 201 However, it may be
 202 used to associate dirty VM pages with file system buffers and thus cause
 203 them to be flushed to physical media sooner rather than later.
 204 .It Dv MAP_PRIVATE
 205 Modifications are private.
 206 .It Dv MAP_SHARED
 207 Modifications are shared.
 208 .It Dv MAP_STACK
 209 .Dv MAP_STACK
 210 implies
 211 .Dv MAP_ANON ,
 212 and
 213 .Fa offset
 214 of 0.
 215 The
 216 .Fa fd
 217 argument
 218 must be -1 and
 219 .Fa prot
 220 must include at least
 221 .Dv PROT_READ
 222 and
 223 .Dv PROT_WRITE .
 224 This option creates
 225 a memory region that grows to at most
 226 .Fa len
 227 bytes in size, starting from the stack top and growing down.
 228 The
 229 stack top is the starting address returned by the call, plus
 230 .Fa len
 231 bytes.
 232 The bottom of the stack at maximum growth is the starting
 233 address returned by the call.
 234 .El
 235 .Pp
 236 The
 237 .Xr close 2
 238 system call does not unmap pages, see
 239 .Xr munmap 2
 240 for further information.
 241 .Pp
 242 The current design does not allow a process to specify the location of
 243 swap space.
 244 In the future we may define an additional mapping type,
 245 .Dv MAP_SWAP ,
 246 in which
 247 the file descriptor argument specifies a file or device to which swapping
 248 should be done.
 249 .Sh RETURN VALUES
 250 Upon successful completion,
 251 .Fn mmap
 252 returns a pointer to the mapped region.
 253 Otherwise, a value of
 254 .Dv MAP_FAILED
 255 is returned and
 256 .Va errno
 257 is set to indicate the error.
 258 .Sh ERRORS
 259 The
 260 .Fn mmap
 261 system call
 262 will fail if:
 263 .Bl -tag -width Er
 264 .It Bq Er EACCES
 265 The flag
 266 .Dv PROT_READ
 267 was specified as part of the
 268 .Fa prot
 269 argument and
 270 .Fa fd
 271 was not open for reading.
 272 The flags
 273 .Dv MAP_SHARED
 274 and
 275 .Dv PROT_WRITE
 276 were specified as part of the
 277 .Fa flags
 278 and
 279 .Fa prot
 280 argument and
 281 .Fa fd
 282 was not open for writing.
 283 .It Bq Er EBADF
 284 The
 285 .Fa fd
 286 argument
 287 is not a valid open file descriptor.
 288 .It Bq Er EINVAL
 289 .Dv MAP_FIXED
 290 was specified and the
 291 .Fa addr
 292 argument was not page aligned, or part of the desired address space
 293 resides out of the valid address space for a user process.
 294 .It Bq Er EINVAL
 295 The
 296 .Fa len
 297 argument
 298 was negative.
 299 .It Bq Er EINVAL
 300 .Dv MAP_ANON
 301 was specified and the
 302 .Fa fd
 303 argument was not -1.
 304 .It Bq Er EINVAL
 305 .Dv MAP_ANON
 306 has not been specified and
 307 .Fa fd
 308 did not reference a regular or character special file.
 309 .It Bq Er EINVAL
 310 The
 311 .Fa offset
 312 argument
 313 was not page-aligned.
 314 (See
 315 .Sx BUGS
 316 below.)
 317 .It Bq Er ENOMEM
 318 .Dv MAP_FIXED
 319 was specified and the
 320 .Fa addr
 321 argument was not available.
 322 .Dv MAP_ANON
 323 was specified and insufficient memory was available.
 324 The system has reached the per-process mmap limit specified in the
 325 .Va vm.max_proc_mmap
 326 sysctl.
 327 .El
 328 .Sh SEE ALSO
 329 .Xr madvise 2 ,
 330 .Xr mincore 2 ,
 331 .Xr minherit 2 ,
 332 .Xr mlock 2 ,
 333 .Xr mprotect 2 ,
 334 .Xr msync 2 ,
 335 .Xr munlock 2 ,
 336 .Xr munmap 2 ,
 337 .Xr getpagesize 3 ,
 338 .Xr make.conf 5
 339 .Sh BUGS
 340 The
 341 .Fa len
 342 argument
 343 is limited to 2GB.
 344 Mmapping slightly more than 2GB does not work, but
 345 it is possible to map a window of size (filesize % 2GB) for file sizes
 346 of slightly less than 2G, 4GB, 6GB and 8GB.
 347 .Pp
 348 The limit is imposed for a variety of reasons.
 349 Most of them have to do
 350 with
 351 .Fx
 352 not wanting to use 64 bit offsets in the VM system due to
 353 the extreme performance penalty.
 354 So
 355 .Fx
 356 uses 32bit page indexes and
 357 this gives
 358 .Fx
 359 a maximum of 8TB filesizes.
 360 It is actually bugs in
 361 the file system code that causes the limit to be further restricted to
 362 1TB (loss of precision when doing blockno calculations).
 363 .Pp
 364 Another reason for the 2GB limit is that file system metadata can
 365 reside at negative offsets.
 366 .Pp
 367 Note that an attempt to
 368 .Fn mmap
 369 zero bytes has no effect and succeeds, while an attempt to
 370 .Fn munmap
 371 zero bytes will return
 372 .Bq Er EINVAL .