bsd/man/man2/mmap.2

   1 .\"     $NetBSD: mmap.2,v 1.5 1995/06/24 10:48:59 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)mmap.2      8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt MMAP 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm mmap
  41 .Nd map files or devices into memory
  42 .Sh SYNOPSIS
  43 .Fd #include <sys/mman.h>
  44 .Ft void *
  45 .Fo mmap
  46 .Fa "void *addr"
  47 .Fa "size_t len"
  48 .Fa "int prot"
  49 .Fa "int flags"
  50 .Fa "int fildes"
  51 .Fa "off_t offset"
  52 .Fc
  53 .Sh DESCRIPTION
  54 The
  55 .Nm mmap
  56 function causes the pages starting at
  57 .Fa addr
  58 and continuing for at most
  59 .Fa len
  60 bytes to be mapped from the object described by
  61 .Fa fildes ,
  62 starting at byte offset
  63 .Fa offset .
  64 If
  65 .Fa offset
  66 or
  67 .Fa len
  68 is not a multiple of the pagesize, the mapped region may extend past the
  69 specified range.
  70 .Pp
  71 If
  72 .Fa addr
  73 is non-zero, it is used as a hint to the system.
  74 (As a convenience to the system, the actual address of the region may differ
  75 from the address supplied.)
  76 If
  77 .Fa addr
  78 is zero, an address will be selected by the system.
  79 The actual starting address of the region is returned.
  80 A successful
  81 .Fa mmap
  82 deletes any previous mapping in the allocated address range.
  83 .Pp
  84 The protections (region accessibility) are specified in the
  85 .Fa prot
  86 argument by
  87 .Em or Ns 'ing
  88 the following values:
  89 .Pp
  90 .Bl -tag -width MAP_FIXEDX
  91 .It Dv PROT_EXEC
  92 Pages may be executed.
  93 .It Dv PROT_READ
  94 Pages may be read.
  95 .It Dv PROT_WRITE
  96 Pages may be written.
  97 .El
  98 .Pp
  99 The
 100 .Fa flags
 101 parameter specifies the type of the mapped object, mapping options,
 102 and whether modifications made to the mapped copy of the page
 103 are private to the process (copy-on-write)
 104 or are to be shared with other references.
 105 Sharing, mapping type, and options are specified in the
 106 .Fa flags
 107 argument by
 108 .Em or Ns 'ing
 109 the following values:
 110 .Pp
 111 .Bl -tag -width MAP_HASSEMAPHOREX
 112 .It Dv MAP_ANON
 113 Map anonymous memory not associated with any specific file.
 114 Mac OS X specific: the file descriptor used for creating
 115 .Dv MAP_ANON
 116 regions can be used to pass some Mach VM flags, and can
 117 be specified as \-1 if no such flags are associated with
 118 the region.  Mach VM flags are defined in
 119 <mach/vm_statistics.h> and the ones that currently apply
 120 to
 121 .Nm mmap
 122 are:
 123 .Pp
 124 VM_FLAGS_PURGABLE       to create Mach purgable (i.e. volatile) memory
 125 VM_MAKE_TAG(tag)        to associate an 8-bit tag with the region
 126 .Pp
 127 <mach/vm_statistics.h> defines some preset tags (with a VM_MEMORY_ prefix).
 128 Users are encouraged to use tags between 240 and 255.
 129 Tags are used by tools such as vmmap(1) to help identify specific memory regions.
 130 .It Dv MAP_FILE
 131 Mapped from a regular file or character-special device memory.  (This is
 132 the default mapping type, and need not be specified.)
 133 .It Dv MAP_FIXED
 134 Do not permit the system to select a different address than the one
 135 specified.
 136 If the specified address cannot be used,
 137 .Nm mmap
 138 will fail.
 139 If MAP_FIXED is specified,
 140 .Fa addr
 141 must be a multiple of the pagesize.
 142 Use of this option is discouraged.
 143 .It Dv MAP_HASSEMAPHORE
 144 Notify the kernel that the region may contain semaphores and that special
 145 handling may be necessary.
 146 .It Dv MAP_PRIVATE
 147 Modifications are private (copy-on-write).
 148 .It Dv MAP_SHARED
 149 Modifications are shared.
 150 .It Dv MAP_NOCACHE
 151 Pages in this mapping are not retained in the kernel's memory cache.
 152 If the system runs low on memory, pages in MAP_NOCACHE mappings will be among
 153 the first to be reclaimed.
 154 This flag is intended for mappings that have little locality and
 155 provides a hint to the kernel that pages in this mapping are unlikely to be needed
 156 again in the near future.
 157 .El
 158 .Pp
 159 Conforming applications must specify either MAP_PRIVATE or MAP_SHARED.
 160 .Pp
 161 The
 162 .Xr close 2
 163 function does not unmap pages, see
 164 .Xr munmap 2
 165 for further information.
 166 .Pp
 167 The current design does not allow a process to specify the location of
 168 swap space.
 169 In the future we may define an additional mapping type,
 170 .Dv MAP_SWAP ,
 171 in which
 172 the file descriptor argument specifies a file or device to which swapping
 173 should be done.
 174 .Sh RETURN VALUES
 175 Upon successful completion,
 176 .Nm mmap
 177 returns a pointer to the mapped region.
 178 Otherwise, a value of -1 is returned and
 179 .Va errno
 180 is set to indicate the error.
 181 .Sh ERRORS
 182 .Fn Mmap
 183 will fail if:
 184 .Bl -tag -width Er
 185 .\" ===========
 186 .It Bq Er EACCES
 187 .Fa Fildes
 188 is not open for reading.
 189 .\" ===========
 190 .It Bq Er EACCES
 191 The flags
 192 .Dv PROT_WRITE
 193 and
 194 .Dv MAP_SHARED
 195 are specified as part of the
 196 .Fa flags
 197 and
 198 .Fa prot
 199 parameters and
 200 .Fa fildes
 201 is not open for writing.
 202 .\" ===========
 203 .It Bq Er EBADF
 204 .Fa fildes
 205 is not a valid file descriptor for an open file.
 206 .It Bq Er EINVAL
 207 .Dv MAP_FIXED
 208 is specified and the
 209 .I addr
 210 parameter is not page aligned.
 211 .\" ===========
 212 .It Bq Er EINVAL
 213 .Fa fildes
 214 does not reference a regular or character special file.
 215 .\" ===========
 216 .It Bq Er EINVAL
 217 .Fa flags
 218 does not include either MAP_PRIVATE or MAP_SHARED.
 219 .\" ===========
 220 .It Bq Er EINVAL
 221 .Fa len
 222 is not greater than zero.
 223 .\" ===========
 224 .It Bq Er EINVAL
 225 .Fa offset
 226 is not a multiple of the page size,
 227 as returned by
 228 .Xr sysconf 3 .
 229 .\" ===========
 230 .It Bq Er EMFILE
 231 The limit on mapped regions (per process or system) is exceeded.
 232 .\" ===========
 233 .It Bq Er ENODEV
 234 The file type for
 235 .Fa fildes
 236 is not supported for mapping.
 237 .\" ===========
 238 .It Bq Er ENOMEM
 239 .Dv MAP_FIXED
 240 is specified and the address range specified
 241 exceeds the address space limit for the process.
 242 .\" ===========
 243 .It Bq Er ENOMEM
 244 .Dv MAP_FIXED
 245 is specified and the address specified by the
 246 .Fa addr
 247 parameter isn't available.
 248 .\" ===========
 249 .It Bq Er ENOMEM
 250 .Dv MAP_ANON
 251 is specified and insufficient memory is available.
 252 .\" ===========
 253 .It Bq Er ENXIO
 254 Addresses in the specified range are invalid for fildes.
 255 .\" ===========
 256 .It Bq Er EOVERFLOW
 257 Addresses in the specified range exceed the maximum offset
 258 set for fildes.
 259 .El
 260 .Sh LEGACY SYNOPSIS
 261 .Fd #include <sys/types.h>
 262 .Fd #include <sys/mman.h>
 263 .Pp
 264 The include file
 265 .In sys/types.h
 266 is necessary.
 267 .Sh COMPATIBILITY
 268 .Fn mmap
 269 now returns with
 270 .Va errno
 271 set to EINVAL in places that historically succeeded.
 272 The rules have changed as follows:
 273 .Bl -bullet
 274 .It
 275 The
 276 .Fa flags
 277 parameter must specify either MAP_PRIVATE or MAP_SHARED.
 278 .It
 279 The
 280 .Fa size
 281 parameter must not be 0.
 282 .It
 283 The
 284 .Fa off
 285 parameter must be a multiple of pagesize,
 286 as returned by
 287 .Fn sysconf .
 288 .El
 289 .Sh "SEE ALSO"
 290 .Xr getpagesize 2 ,
 291 .Xr madvise 2 ,
 292 .Xr mincore 2 ,
 293 .Xr mlock 2 ,
 294 .Xr mprotect 2 ,
 295 .Xr msync 2 ,
 296 .Xr munmap 2 ,
 297 .Xr sysconf 3 ,
 298 .Xr compat 5