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
 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 obsolete 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_PRIVATE
 215 Modifications are private.
 216 .It Dv MAP_SHARED
 217 Modifications are shared.
 218 .It Dv MAP_STACK
 219 .Dv MAP_STACK
 220 implies
 221 .Dv MAP_ANON ,
 222 and
 223 .Fa offset
 224 of 0.
 225 The
 226 .Fa fd
 227 argument
 228 must be -1 and
 229 .Fa prot
 230 must include at least
 231 .Dv PROT_READ
 232 and
 233 .Dv PROT_WRITE .
 234 This option creates
 235 a memory region that grows to at most
 236 .Fa len
 237 bytes in size, starting from the stack top and growing down.
 238 The
 239 stack top is the starting address returned by the call, plus
 240 .Fa len
 241 bytes.
 242 The bottom of the stack at maximum growth is the starting
 243 address returned by the call.
 244 .El
 245 .Pp
 246 The
 247 .Xr close 2
 248 system call does not unmap pages, see
 249 .Xr munmap 2
 250 for further information.
 251 .Pp
 252 The current design does not allow a process to specify the location of
 253 swap space.
 254 In the future we may define an additional mapping type,
 255 .Dv MAP_SWAP ,
 256 in which
 257 the file descriptor argument specifies a file or device to which swapping
 258 should be done.
 259 .Sh RETURN VALUES
 260 Upon successful completion,
 261 .Fn mmap
 262 returns a pointer to the mapped region.
 263 Otherwise, a value of
 264 .Dv MAP_FAILED
 265 is returned and
 266 .Va errno
 267 is set to indicate the error.
 268 .Sh ERRORS
 269 The
 270 .Fn mmap
 271 system call
 272 will fail if:
 273 .Bl -tag -width Er
 274 .It Bq Er EACCES
 275 The flag
 276 .Dv PROT_READ
 277 was specified as part of the
 278 .Fa prot
 279 argument and
 280 .Fa fd
 281 was not open for reading.
 282 The flags
 283 .Dv MAP_SHARED
 284 and
 285 .Dv PROT_WRITE
 286 were specified as part of the
 287 .Fa flags
 288 and
 289 .Fa prot
 290 argument and
 291 .Fa fd
 292 was not open for writing.
 293 .It Bq Er EBADF
 294 The
 295 .Fa fd
 296 argument
 297 is not a valid open file descriptor.
 298 .It Bq Er EINVAL
 299 .Dv MAP_FIXED
 300 was specified and the
 301 .Fa addr
 302 argument was not page aligned, or part of the desired address space
 303 resides out of the valid address space for a user process.
 304 .It Bq Er EINVAL
 305 The
 306 .Fa len
 307 argument
 308 was negative.
 309 .It Bq Er EINVAL
 310 .Dv MAP_ANON
 311 was specified and the
 312 .Fa fd
 313 argument was not -1.
 314 .It Bq Er EINVAL
 315 .Dv MAP_ANON
 316 has not been specified and
 317 .Fa fd
 318 did not reference a regular or character special file.
 319 .It Bq Er EINVAL
 320 The
 321 .Fa offset
 322 argument
 323 was not page-aligned.
 324 (See
 325 .Sx BUGS
 326 below.)
 327 .It Bq Er ENOMEM
 328 .Dv MAP_FIXED
 329 was specified and the
 330 .Fa addr
 331 argument was not available.
 332 .Dv MAP_ANON
 333 was specified and insufficient memory was available.
 334 The system has reached the per-process mmap limit specified in the
 335 .Va vm.max_proc_mmap
 336 sysctl.
 337 .El
 338 .Sh SEE ALSO
 339 .Xr madvise 2 ,
 340 .Xr mincore 2 ,
 341 .Xr minherit 2 ,
 342 .Xr mlock 2 ,
 343 .Xr mprotect 2 ,
 344 .Xr msync 2 ,
 345 .Xr munlock 2 ,
 346 .Xr munmap 2 ,
 347 .Xr getpagesize 3 ,
 348 .Xr make.conf 5
 349 .Sh BUGS
 350 The
 351 .Fa len
 352 argument
 353 is limited to 2GB.
 354 Mmapping slightly more than 2GB does not work, but
 355 it is possible to map a window of size (filesize % 2GB) for file sizes
 356 of slightly less than 2G, 4GB, 6GB and 8GB.
 357 .Pp
 358 The limit is imposed for a variety of reasons.
 359 Most of them have to do
 360 with
 361 .Fx
 362 not wanting to use 64 bit offsets in the VM system due to
 363 the extreme performance penalty.
 364 So
 365 .Fx
 366 uses 32bit page indexes and
 367 this gives
 368 .Fx
 369 a maximum of 8TB filesizes.
 370 It is actually bugs in
 371 the file system code that causes the limit to be further restricted to
 372 1TB (loss of precision when doing blockno calculations).
 373 .Pp
 374 Another reason for the 2GB limit is that file system metadata can
 375 reside at negative offsets.
 376 .Pp
 377 Note that an attempt to
 378 .Fn mmap
 379 zero bytes has no effect and succeeds, while an attempt to
 380 .Fn munmap
 381 zero bytes will return
 382 .Bq Er EINVAL .