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