bsd/man/man2/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: src/lib/libc/sys/mmap.2,v 1.56 2007/01/09 00:28:15 imp Exp $
  30 .\"
  31 .Dd April 21, 2006
  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 offset
  56 or
  57 .Fa len
  58 is not a multiple of the pagesize, the mapped region may extend past the
  59 specified range.
  60 Any extension beyond the end of the mapped object will be zero-filled.
  61 .Pp
  62 The
  63 .Fa addr
  64 argument is used by the system to determine the starting address of the mapping,
  65 and its interpretation is dependent on the setting of the MAP_FIXED flag.
  66 If MAP_FIXED is specified in
  67 .Fa flags ,
  68 the system will try to place the mapping at the specified address,
  69 possibly removing a
  70 mapping that already exists at that location.
  71 If MAP_FIXED is not specified,
  72 then the system will attempt to use the range of addresses starting at
  73 .Fa addr
  74 if they do not overlap any existing mappings,
  75 including memory allocated by malloc(3) and other such allocators.
  76 Otherwise,
  77 the system will choose an alternate address for the mapping (using an implementation
  78 dependent algorithm)
  79 that does not overlap any existing
  80 mappings.
  81 In other words,
  82 without MAP_FIXED the system will attempt to find an empty location in the address space if the specified address
  83 range has already been mapped by something else.
  84 If
  85 .Fa addr
  86 is zero and MAP_FIXED is not specified,
  87 then an address will be selected by the system so as not to overlap
  88 any existing mappings in the address space.
  89 In all cases,
  90 the actual starting address of the region is returned.
  91 If MAP_FIXED is specified,
  92 a successful
  93 .Fa mmap
  94 deletes any previous mapping in the allocated address range.
  95 Previous mappings are never deleted if MAP_FIXED is not specified.
  96 .Pp
  97 The protections (region accessibility) are specified in the
  98 .Fa prot
  99 argument by
 100 .Em or Ns 'ing
 101 the following values:
 102 .Pp
 103 .Bl -tag -width PROT_WRITE -compact
 104 .It Dv PROT_NONE
 105 Pages may not be accessed.
 106 .It Dv PROT_READ
 107 Pages may be read.
 108 .It Dv PROT_WRITE
 109 Pages may be written.
 110 .It Dv PROT_EXEC
 111 Pages may be executed.
 112 .El
 113 .Pp
 114 Note that, due to hardware limitations, on some platforms PROT_WRITE may
 115 imply PROT_READ, and PROT_READ may imply PROT_EXEC.  Portable programs
 116 should not rely on these flags being separately enforcable.
 117 .Pp
 118 The
 119 .Fa flags
 120 argument specifies the type of the mapped object, mapping options and
 121 whether modifications made to the mapped copy of the page are private
 122 to the process (copy-on-write) or are to be shared with other references.
 123 Sharing, mapping type and options are specified in the
 124 .Fa flags
 125 argument by
 126 .Em or Ns 'ing
 127 the following values:
 128 .Bl -tag -width MAP_HASSEMAPHORE
 129 .It Dv MAP_ANONYMOUS
 130 Synonym for
 131 .Dv MAP_ANON.
 132 .It Dv MAP_ANON
 133 Map anonymous memory not associated with any specific file.
 134 The
 135 .Fa offset
 136 argument is ignored.
 137 Mac OS X specific: the file descriptor used for creating
 138 .Dv MAP_ANON
 139 regions can be used to pass some Mach VM flags, and can
 140 be specified as \-1 if no such flags are associated with
 141 the region.  Mach VM flags are defined in
 142 <mach/vm_statistics.h> and the ones that currently apply
 143 to
 144 .Nm mmap
 145 are:
 146 .Pp
 147 VM_FLAGS_PURGABLE       to create Mach purgable (i.e. volatile) memory
 148 .Pp
 149 VM_MAKE_TAG(tag)        to associate an 8-bit tag with the region
 150 .br
 151 <mach/vm_statistics.h> defines some preset tags (with a VM_MEMORY_ prefix).
 152 Users are encouraged to use tags between 240 and 255.
 153 Tags are used by tools such as vmmap(1) to help identify specific memory regions.
 154 .Pp
 155 VM_FLAGS_SUPERPAGE_SIZE_*       to use superpages for the allocation.
 156 See <mach/vm_statistics.h> for supported architectures and sizes (or use
 157 VM_FLAGS_SUPERPAGE_SIZE_ANY to have the kernel choose a size).
 158 The specified size must be divisible by the superpage size (except for
 159 VM_FLAGS_SUPERPAGE_SIZE_ANY), and if you use MAP_FIXED, the specified address
 160 must be properly aligned. If the system cannot satisfy the request with superpages,
 161 the call will fail. Note that currently, superpages are always wired and not
 162 inherited by children of the process.
 163 .It Dv MAP_FILE
 164 Mapped from a regular file.  (This is
 165 the default mapping type, and need not be specified.)
 166 .It Dv MAP_FIXED
 167 Do not permit the system to select a different address than the one
 168 specified.
 169 If the specified address cannot be used,
 170 .Fn mmap
 171 will fail.
 172 If
 173 .Dv MAP_FIXED
 174 is specified,
 175 .Fa addr
 176 must be a multiple of the pagesize.
 177 If a
 178 .Dv MAP_FIXED
 179 request is successful, the mapping established by
 180 .Fn mmap
 181 replaces any previous mappings for the process' pages in the range from
 182 .Fa addr
 183 to
 184 .Fa addr
 185 +
 186 .Fa len .
 187 Use of this option is discouraged.
 188 .It Dv MAP_HASSEMAPHORE
 189 Notify the kernel that the region may contain semaphores and that special
 190 handling may be necessary.
 191 .It Dv MAP_PRIVATE
 192 Modifications are private (copy-on-write).
 193 .It Dv MAP_SHARED
 194 Modifications are shared.
 195 .It Dv MAP_NOCACHE
 196 Pages in this mapping are not retained in the kernel's memory cache.
 197 If the system runs low on memory, pages in MAP_NOCACHE mappings will be among
 198 the first to be reclaimed.
 199 This flag is intended for mappings that have little locality and
 200 provides a hint to the kernel that pages in this mapping are unlikely to be needed
 201 again in the near future.
 202 .El
 203 .Pp
 204 Conforming applications must specify either MAP_PRIVATE or MAP_SHARED.
 205 .Pp
 206 The
 207 .Xr close 2
 208 system call does not unmap pages, see
 209 .Xr munmap 2
 210 for further information.
 211 .Pp
 212 The current design does not allow a process to specify the location of
 213 swap space.
 214 In the future we may define an additional mapping type,
 215 .Dv MAP_SWAP ,
 216 in which
 217 the file descriptor argument specifies a file or device to which swapping
 218 should be done.
 219 .Sh RETURN VALUES
 220 Upon successful completion,
 221 .Fn mmap
 222 returns a pointer to the mapped region.
 223 Otherwise, a value of
 224 .Dv MAP_FAILED
 225 is returned and
 226 .Va errno
 227 is set to indicate the error.
 228 .Sh ERRORS
 229 The
 230 .Fn mmap
 231 system call
 232 will fail if:
 233 .Bl -tag -width Er
 234 .It Bq Er EACCES
 235 The flag
 236 .Dv PROT_READ
 237 was specified as part of the
 238 .Fa prot
 239 argument and
 240 .Fa fd
 241 was not open for reading.
 242 The flags
 243 .Dv MAP_SHARED
 244 and
 245 .Dv PROT_WRITE
 246 were specified as part of the
 247 .Fa flags
 248 and
 249 .Fa prot
 250 argument and
 251 .Fa fd
 252 was not open for writing.
 253 .It Bq Er EBADF
 254 The
 255 .Fa fd
 256 argument
 257 is not a valid open file descriptor.
 258 .It Bq Er EINVAL
 259 .Dv MAP_FIXED
 260 was specified and the
 261 .Fa addr
 262 argument was not page aligned, or part of the desired address space
 263 resides out of the valid address space for a user process.
 264 .It Bq Er EINVAL
 265 .Fa flags
 266 does not include either MAP_PRIVATE or MAP_SHARED.
 267 .It Bq Er EINVAL
 268 The
 269 .Fa len
 270 argument
 271 was negative or zero. Historically, the system call would not return an error if the argument was zero.
 272 See other potential additional restrictions in the
 273 COMPATIBILITY section below.
 274 .It Bq Er EINVAL
 275 The
 276 .Fa offset
 277 argument
 278 was not page-aligned based on the page size as returned by getpagesize(3).
 279 .It Bq Er ENODEV
 280 .Dv MAP_ANON
 281 has not been specified and the file
 282 .Fa fd
 283 refers to does not support mapping.
 284 .It Bq Er ENOMEM
 285 .Dv MAP_FIXED
 286 was specified and the
 287 .Fa addr
 288 argument was not available.
 289 .Dv MAP_FIXED
 290 was specified and the address range specified exceeds the address space
 291 limit for the process.
 292 .Dv MAP_ANON
 293 was specified and insufficient memory was available.
 294 .It Bq Er ENXIO
 295 Addresses in the specified range are invalid for
 296 .Fa fd .
 297 .It Bq Er EOVERFLOW
 298 Addresses in the specified range exceed the maximum offset
 299 set for
 300 .Fa fd .
 301 .El
 302 .Sh LEGACY SYNOPSIS
 303 .Fd #include <sys/types.h>
 304 .Fd #include <sys/mman.h>
 305 .Pp
 306 The include file
 307 .In sys/types.h
 308 is necessary.
 309 .Sh COMPATIBILITY
 310 .Fn mmap
 311 now returns with
 312 .Va errno
 313 set to EINVAL in places that historically succeeded.
 314 The rules have changed as follows:
 315 .Bl -bullet
 316 .It
 317 The
 318 .Fa flags
 319 parameter must specify either MAP_PRIVATE or MAP_SHARED.
 320 .It
 321 The
 322 .Fa len
 323 parameter must not be 0.
 324 .It
 325 The
 326 .Fa off
 327 parameter must be a multiple of pagesize,
 328 as returned by
 329 .Fn sysconf .
 330 .El
 331 .Sh SEE ALSO
 332 .Xr madvise 2 ,
 333 .Xr mincore 2 ,
 334 .Xr minherit 2 ,
 335 .Xr mlock 2 ,
 336 .Xr mprotect 2 ,
 337 .Xr msync 2 ,
 338 .Xr munlock 2 ,
 339 .Xr munmap 2 ,
 340 .Xr shmat 2 ,
 341 .Xr getpagesize 3