man2/mmap.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl>
   4 .\" and Copyright (C) 2006 Michael Kerrisk <mtk-manpages@gmx.net>
   5 .\"
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\"
  26 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
  27 .\" Modified 2000-03-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
  28 .\" Modified 2001-10-04 by John Levon <moz@compsoc.man.ac.uk>
  29 .\" Modified 2003-02-02 by Andi Kleen <ak@muc.de>
  30 .\" Modified 2003-05-21 by Michael Kerrisk <mtk-manpages@gmx.net>
  31 .\"     MAP_LOCKED works from 2.5.37
  32 .\" Modified 2004-06-17 by Michael Kerrisk <mtk-manpages@gmx.net>
  33 .\" Modified 2004-09-11 by aeb
  34 .\" Modified 2004-12-08, from Eric Estievenart <eric.estievenart@free.fr>
  35 .\" Modified 2004-12-08, mtk, formatting tidy-ups
  36 .\" Modified 2006-12-04, mtk, various parts rewritten
  37 .\"
  38 .TH MMAP 2 2006-12-04 "Linux" "Linux Programmer's Manual"
  39 .SH NAME
  40 mmap, munmap \- map or unmap files or devices into memory
  41 .SH SYNOPSIS
  42 .nf
  43 .B #include <sys/mman.h>
  44 .sp
  45 .BI "void *mmap(void *" start ", size_t " length \
  46 ", int " prot ", int " flags ,
  47 .BI "           int " fd ", off_t " offset );
  48 .sp
  49 .BI "int munmap(void *" start ", size_t " length );
  50 .fi
  51 .SH DESCRIPTION
  52 .BR mmap ()
  53 creates a new mapping in the virtual address space of
  54 the calling process.
  55 The starting address for the new mapping is specified in
  56 .IR start .
  57 The
  58 .I length
  59 argument specifies the length of the mapping.
  60
  61 If
  62 .I start
  63 is NULL,
  64 then the kernel chooses the address at which to create the mapping;
  65 this is the most portable method of creating a new mapping.
  66 If
  67 .I start
  68 is not NULL,
  69 then the kernel takes it as a hint about where to place the mapping;
  70 on Linux, the mapping will be created at the next higher page boundary.
  71 The address of the new mapping is returned as the result of the call.
  72
  73 The contents of a file mapping (as opposed to an anonymous mapping; see
  74 .B MAP_ANONYMOUS
  75 below), are initialized using
  76 .I length
  77 bytes starting at offset
  78 .I offset
  79 in the file (or other object) referred to by the file descriptor
  80 .IR fd .
  81 .I offset
  82 must be a multiple of the page size as returned by
  83 .IR sysconf(_SC_PAGE_SIZE) .
  84 .LP
  85 The
  86 .I prot
  87 argument describes the desired memory protection of the mapping
  88 (and must not conflict with the open mode of the file).
  89 It is either
  90 .B PROT_NONE
  91 or the bitwise OR of one or more of the following flags:
  92 .TP 1.1i
  93 .B PROT_EXEC
  94 Pages may be executed.
  95 .TP
  96 .B PROT_READ
  97 Pages may be read.
  98 .TP
  99 .B PROT_WRITE
 100 Pages may be written.
 101 .TP
 102 .B PROT_NONE
 103 Pages may not be accessed.
 104 .LP
 105 The
 106 .I flags
 107 argument determines whether updates to the mapping
 108 are visible to other processes mapping the same region,
 109 and whether updates are caried through to the underlying file.
 110 This behavior is determined by including exactly one
 111 of the following values in
 112 .IR flags :
 113 .TP 1.1i
 114 .B MAP_SHARED
 115 Share this mapping.
 116 Updates to the mapping are visible to other processes that map this file,
 117 and are carried through to the underlying file.
 118 The file may not actually be updated until
 119 .BR msync (2)
 120 or
 121 .BR munmap (2)
 122 is called.
 123 .TP
 124 .B MAP_PRIVATE
 125 Create a private copy-on-write mapping.
 126 Updates to the mapping are not visible to other processes
 127 mapping the same file, and are not carried through to
 128 the underlying file.
 129 It is unspecified whether changes made to the file after the
 130 .BR mmap ()
 131 call are visible in the mapped region.
 132 .LP
 133 Both of these flags are described in POSIX.1-2001.
 134
 135 In addition, zero or more of the following values can be ORed in
 136 .IR flags :
 137 .TP
 138 .B MAP_32BIT
 139 Put the mapping into the first 2GB of the process address space.
 140 Ignored when
 141 .B MAP_FIXED
 142 is set.
 143 This flag is currently only supported on x86-64 for 64bit programs.
 144 .TP
 145 .B MAP_ANON
 146 Synonym for
 147 .BR MAP_ANONYMOUS .
 148 Deprecated.
 149 .TP
 150 .B MAP_ANONYMOUS
 151 The mapping is not backed by any file;
 152 its contents are initialized to zero.
 153 The
 154 .I fd
 155 and
 156 .I offset
 157 arguments are ignored;
 158 however, some implementations require
 159 .I fd
 160 to be \-1 if
 161 .B MAP_ANONYMOUS
 162 (or
 163 .BR MAP_ANON )
 164 is specified,
 165 and portable applications should ensure this.
 166 The use of
 167 .B MAP_ANONYMOUS
 168 in conjunction with
 169 .B MAP_SHARED
 170 is only supported on Linux since kernel 2.4.
 171 .TP
 172 .B MAP_DENYWRITE
 173 This flag is ignored.
 174 .\" Introduced in 1.1.36, removed in 1.3.24.
 175 (Long ago, it signaled that attempts to write to the underlying file
 176 should fail with
 177 .BR ETXTBUSY .
 178 But this was a source of denial-of-service attacks.)
 179 .TP
 180 .B MAP_EXECUTABLE
 181 This flag is ignored.
 182 .\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link.
 183 .\" (Long ago, it signaled that the underlying file is an executable.
 184 .\" However, that information was not really used anywhere.)
 185 .\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of
 186 .\" MAP_DENYWRITE?
 187 .TP
 188 .B MAP_FILE
 189 Compatibility flag.
 190 Ignored.
 191 .\" On some systems, this was required as the opposite of
 192 .\" MAP_ANONYMOUS -- mtk, 1 May 2007
 193 .TP
 194 .B MAP_FIXED
 195 Don't interpret
 196 .I start
 197 as a hint: place the mapping at exactly that address.
 198 .I start
 199 must be a multiple of the page size.
 200 If the memory region specified by
 201 .I start
 202 and
 203 .I len
 204 overlaps pages of any existing mapping(s), then the overlapped
 205 part of the existing mapping(s) will be discarded.
 206 If the specified address cannot be used,
 207 .BR mmap ()
 208 will fail.
 209 Because requiring a fixed address for a mapping is less portable,
 210 the use of this option is discouraged.
 211 .TP
 212 .B MAP_GROWSDOWN
 213 Used for stacks.
 214 Indicates to the kernel virtual memory system that the mapping
 215 should extend downwards in memory.
 216 .TP
 217 .BR MAP_LOCKED " (since Linux 2.5.37)"
 218 Lock the pages of the mapped region into memory in the manner of
 219 .BR mlock (2) .
 220 This flag is ignored in older kernels.
 221 .\" If set, the mapped pages will not be swapped out.
 222 .TP
 223 .BR MAP_NONBLOCK " (since Linux 2.5.46)"
 224 Only meaningful in conjunction with
 225 .BR MAP_POPULATE .
 226 Don't perform read-ahead:
 227 only create page tables entries for pages
 228 that are already present in RAM.
 229 .TP
 230 .B MAP_NORESERVE
 231 Do not reserve swap space for this mapping.
 232 When swap space is reserved, one has the guarantee
 233 that it is possible to modify the mapping.
 234 When swap space is not reserved one might get
 235 .B SIGSEGV
 236 upon a write
 237 if no physical memory is available.
 238 See also the discussion of the file
 239 .I /proc/sys/vm/overcommit_memory
 240 in
 241 .BR proc (5).
 242 In kernels before 2.6, this flag only had effect for
 243 private writable mappings.
 244 .TP
 245 .BR MAP_POPULATE " (since Linux 2.5.46)"
 246 Populate (prefault) page tables for a file mapping,
 247 by performing read-ahead on the file.
 248 Later accesses to the mapping will not be blocked by page faults.
 249 .LP
 250 Of the above flags, only
 251 .B MAP_FIXED
 252 is specified in POSIX.1-2001.
 253 However, most systems also support
 254 .B MAP_ANONYMOUS
 255 (or its synonym
 256 .BR MAP_ANON ).
 257 .LP
 258 Some systems document the additional flags MAP_AUTOGROW, MAP_AUTORESRV,
 259 MAP_COPY, and MAP_LOCAL.
 260 .LP
 261 Memory mapped by
 262 .BR mmap ()
 263 is preserved across
 264 .BR fork (2),
 265 with the same attributes.
 266 .LP
 267 A file is mapped in multiples of the page size.
 268 For a file that is not
 269 a multiple of the page size, the remaining memory is zeroed when mapped,
 270 and writes to that region are not written out to the file.
 271 The effect of
 272 changing the size of the underlying file of a mapping on the pages that
 273 correspond to added or removed regions of the file is unspecified.
 274
 275 The
 276 .BR munmap ()
 277 system call deletes the mappings for the specified address range, and
 278 causes further references to addresses within the range to generate
 279 invalid memory references.
 280 The region is also automatically unmapped
 281 when the process is terminated.
 282 On the other hand, closing the file
 283 descriptor does not unmap the region.
 284 .LP
 285 The address
 286 .I start
 287 must be a multiple of the page size.
 288 All pages containing a part
 289 of the indicated range are unmapped, and subsequent references
 290 to these pages will generate
 291 .BR SIGSEGV .
 292 It is not an error if the
 293 indicated range does not contain any mapped pages.
 294
 295 For file-backed mappings, the
 296 .I st_atime
 297 field for the mapped file may be updated at any time between the
 298 .BR mmap ()
 299 and the corresponding unmapping; the first reference to a mapped
 300 page will update the field if it has not been already.
 301 .LP
 302 The
 303 .I st_ctime
 304 and
 305 .I st_mtime
 306 field for a file mapped with
 307 .B PROT_WRITE
 308 and
 309 .B MAP_SHARED
 310 will be updated after
 311 a write to the mapped region, and before a subsequent
 312 .BR msync (2)
 313 with the
 314 .B MS_SYNC
 315 or
 316 .BR MS_ASYNC
 317 flag, if one occurs.
 318 .SH "RETURN VALUE"
 319 On success,
 320 .BR mmap ()
 321 returns a pointer to the mapped area.
 322 On error, the value
 323 .B MAP_FAILED
 324 (that is,
 325 .I "(void *) \-1)"
 326 is returned, and
 327 .I errno
 328 is set appropriately.
 329 On success,
 330 .BR munmap ()
 331 returns 0, on failure \-1, and
 332 .I errno
 333 is set (probably to
 334 .BR EINVAL ).
 335 .SH ERRORS
 336 .TP
 337 .B EACCES
 338 A file descriptor refers to a non-regular file.
 339 Or
 340 .B MAP_PRIVATE
 341 was requested, but
 342 .I fd
 343 is not open for reading.
 344 Or
 345 .B MAP_SHARED
 346 was requested and
 347 .B PROT_WRITE
 348 is set, but
 349 .I fd
 350 is not open in read/write (O_RDWR) mode.
 351 Or
 352 .B PROT_WRITE
 353 is set, but the file is append-only.
 354 .TP
 355 .B EAGAIN
 356 The file has been locked, or too much memory has been locked (see
 357 .BR setrlimit (2)).
 358 .TP
 359 .B EBADF
 360 .I fd
 361 is not a valid file descriptor (and
 362 .B MAP_ANONYMOUS
 363 was not set).
 364 .TP
 365 .B EINVAL
 366 We don't like
 367 .IR start ,
 368 .IR length ,
 369 or
 370 .IR offset
 371 (e.g., they are too large, or not aligned on a page boundary).
 372 .TP
 373 .B EINVAL
 374 (since Linux 2.6.12),
 375 .I length
 376 was 0.
 377 .TP
 378 .B EINVAL
 379 .I flags
 380 contained neither
 381 .B MAP_PRIVATE
 382 or
 383 .BR MAP_SHARED ,
 384 or contained both of these values.
 385 .TP
 386 .B ENFILE
 387 .\" This is for shared anonymous segments
 388 .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
 389 The system limit on the total number of open files has been reached.
 390 .\" .TP
 391 .\" .B ENOEXEC
 392 .\" A file could not be mapped for reading.
 393 .TP
 394 .B ENODEV
 395 The underlying filesystem of the specified file does not support
 396 memory mapping.
 397 .TP
 398 .B ENOMEM
 399 No memory is available, or the process's maximum number of mappings would
 400 have been exceeded.
 401 .TP
 402 .B EPERM
 403 The
 404 .I prot
 405 argument asks for
 406 .B PROT_EXEC
 407 but the mapped area belongs to a file on a filesystem that
 408 was mounted no-exec.
 409 .\" (Since 2.4.25 / 2.6.0.)
 410 .TP
 411 .B ETXTBSY
 412 .B MAP_DENYWRITE
 413 was set but the object specified by
 414 .I fd
 415 is open for writing.
 416 .LP
 417 Use of a mapped region can result in these signals:
 418 .TP
 419 .B SIGSEGV
 420 Attempted write into a region mapped as read-only.
 421 .TP
 422 .B SIGBUS
 423 Attempted access to a portion of the buffer that does not correspond
 424 to the file (for example, beyond the end of the file, including the
 425 case where another process has truncated the file).
 426 .SH "CONFORMING TO"
 427 SVr4, 4.4BSD, POSIX.1-2001.
 428 .\" SVr4 documents additional error codes ENXIO and ENODEV.
 429 .\" SUSv2 documents additional error codes EMFILE and EOVERFLOW.
 430 .SH AVAILABILITY
 431 On POSIX systems on which
 432 .BR mmap (),
 433 .BR msync (2)
 434 and
 435 .BR munmap ()
 436 are available,
 437 .B _POSIX_MAPPED_FILES
 438 is defined in \fI<unistd.h>\fP to a value greater than 0. (See also
 439 .BR sysconf (3).)
 440 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
 441 .\" -1: unavailable, 0: ask using sysconf().
 442 .\" glibc defines it to 1.
 443 .SH NOTES
 444 It is architecture dependent whether
 445 .B PROT_READ
 446 implies
 447 .B PROT_EXEC
 448 or not.
 449 Portable programs should always set
 450 .B PROT_EXEC
 451 if they intend to execute code in the new mapping.
 452 .SH BUGS
 453 On Linux there are no guarantees like those suggested above under
 454 .BR MAP_NORESERVE .
 455 By default, any process can be killed
 456 at any moment when the system runs out of memory.
 457
 458 In kernels before 2.6.7, the
 459 .B MAP_POPULATE
 460 flag only has effect if
 461 .I prot
 462 is specified as
 463 .BR PROT_NONE .
 464
 465 SUSv3 specifies that
 466 .BR mmap ()
 467 should fail if
 468 .I length
 469 is 0.
 470 However, in kernels before 2.6.12,
 471 .BR mmap ()
 472 succeeded in this case: no mapping was created and the call returned
 473 .IR start .
 474 Since kernel 2.6.12,
 475 .BR mmap ()
 476 fails with the error
 477 .B EINVAL
 478 for this case.
 479 .SH "SEE ALSO"
 480 .BR getpagesize (2),
 481 .BR mincore (2),
 482 .BR mlock (2),
 483 .BR mmap2 (2),
 484 .BR mremap (2),
 485 .BR msync (2),
 486 .BR remap_file_pages (2),
 487 .BR setrlimit (2),
 488 .BR shm_open (3)
 489 .br
 490 B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391.
 491 .\"
 492 .\" Repeat after me: private read-only mappings are 100% equivalent to
 493 .\" shared read-only mappings. No ifs, buts, or maybes. -- Linus