-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl>
.\" and Copyright (C) 2006, 2007 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified 2000-03-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
.\" 2007-07-10, mtk, Added an example program.
.\" 2008-11-18, mtk, document MAP_STACK
.\"
-.TH MMAP 2 2010-06-20 "Linux" "Linux Programmer's Manual"
+.TH MMAP 2 2013-04-17 "Linux" "Linux Programmer's Manual"
.SH NAME
mmap, munmap \- map or unmap files or devices into memory
.SH SYNOPSIS
.BI " int " fd ", off_t " offset );
.BI "int munmap(void *" addr ", size_t " length );
.fi
+
+See NOTES for information on feature test macro requirements.
.SH DESCRIPTION
.BR mmap ()
creates a new mapping in the virtual address space of
.TP
.BR MAP_32BIT " (since Linux 2.4.20, 2.6)"
Put the mapping into the first 2 Gigabytes of the process address space.
-This flag is only supported on x86-64, for 64-bit programs.
+This flag is supported only on x86-64, for 64-bit programs.
It was added to allow thread stacks to be allocated somewhere
in the first 2GB of memory,
so as to improve context-switch performance on some early
.B MAP_ANONYMOUS
in conjunction with
.B MAP_SHARED
-is only supported on Linux since kernel 2.4.
+is supported on Linux only since kernel 2.4.
.TP
.B MAP_DENYWRITE
This flag is ignored.
.TP
.BR MAP_HUGETLB " (since Linux 2.6.32)"
Allocate the mapping using "huge pages."
-See the kernel source file
+See the Linux kernel source file
.I Documentation/vm/hugetlbpage.txt
for further information.
.TP
Only meaningful in conjunction with
.BR MAP_POPULATE .
Don't perform read-ahead:
-only create page tables entries for pages
+create page tables entries only for pages
that are already present in RAM.
Since Linux 2.6.23, this flag causes
.BR MAP_POPULATE
.I /proc/sys/vm/overcommit_memory
in
.BR proc (5).
-In kernels before 2.6, this flag only had effect for
+In kernels before 2.6, this flag had effect only for
private writable mappings.
.TP
.BR MAP_POPULATE " (since Linux 2.5.46)"
For a file mapping, this causes read-ahead on the file.
Later accesses to the mapping will not be blocked by page faults.
.BR MAP_POPULATE
-is only supported for private mappings since Linux 2.6.23.
+is supported for private mappings only since Linux 2.6.23.
.TP
.BR MAP_STACK " (since Linux 2.6.27)"
Allocate the mapping at an address suitable for a process
.BR MAP_UNINITIALIZED " (since Linux 2.6.33)"
Don't clear anonymous pages.
This flag is intended to improve performance on embedded devices.
-This flag is only honored if the kernel was configured with the
+This flag is honored only if the kernel was configured with the
.B CONFIG_MMAP_ALLOW_UNINITIALIZED
option.
Because of the security implications,
or
.B MS_ASYNC
flag, if one occurs.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
On success,
.BR mmap ()
returns a pointer to the mapped area.
was set but the object specified by
.I fd
is open for writing.
+.TP
+.B EOVERFLOW
+On 32-bit architecture together with the large file extension
+(i.e., using 64-bit
+.IR off_t ):
+the number of pages used for
+.I length
+plus number of pages used for
+.I offset
+would overflow
+.I "unsigned long"
+(32 bits).
.LP
Use of a mapped region can result in these signals:
.TP
Attempted access to a portion of the buffer that does not correspond
to the file (for example, beyond the end of the file, including the
case where another process has truncated the file).
-.SH "CONFORMING TO"
+.SH CONFORMING TO
SVr4, 4.4BSD, POSIX.1-2001.
.\" SVr4 documents additional error codes ENXIO and ENODEV.
.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW.
.\" -1: unavailable, 0: ask using sysconf().
.\" glibc defines it to 1.
.SH NOTES
-Since kernel 2.4, this system call has been superseded by
-.BR mmap2 (2).
-Nowadays,
+This page describes the interface provided by the glibc
+.BR mmap ()
+wrapper function.
+Originally, this function invoked a system call of the same name.
+Since kernel 2.4, that system call has been superseded by
+.BR mmap2 (2),
+and nowadays
.\" Since around glibc 2.1/2.2, depending on the platform.
the glibc
.BR mmap ()
flag is specified, and
.I addr
is 0 (NULL), then the mapped address will be 0 (NULL).
+
+Certain
+.I flags
+constants are defined only if either
+.BR _BSD_SOURCE
+or
+.BR _SVID_SOURCE
+is defined.
+(Requiring
+.BR _GNU_SOURCE
+also suffices,
+and requiring that macro specifically would have been more logical,
+since these flags are all Linux specific.)
+The relevant flags are:
+.BR MAP_32BIT ,
+.BR MAP_ANONYMOUS
+(and the synonym
+.BR MAP_ANON ),
+.BR MAP_DENYWRITE ,
+.BR MAP_EXECUTABLE ,
+.BR MAP_FILE ,
+.BR MAP_GROWSDOWN ,
+.BR MAP_HUGETLB ,
+.BR MAP_LOCKED ,
+.BR MAP_NONBLOCK ,
+.BR MAP_NORESERVE ,
+.BR MAP_POPULATE ,
+and
+.BR MAP_STACK .
.SH BUGS
On Linux there are no guarantees like those suggested above under
.BR MAP_NORESERVE .
In kernels before 2.6.7, the
.B MAP_POPULATE
-flag only has effect if
+flag has effect only if
.I prot
is specified as
.BR PROT_NONE .
fails with the error
.B EINVAL
for this case.
+
+POSIX specifies that the system shall always
+zero fill any partial page at the end
+of the object and that system will never write any modification of the
+object beyond its end.
+On Linux, when you write data to such partial page after the end
+of the object, the data stays in the page cache even after the file
+is closed and unmapped
+and even though the data is never written to the file itself,
+subsequent mappings may see the modified content.
+In some cases, this could be fixed by calling
+.BR msync (2)
+before the unmap takes place;
+however, this doesn't work on tmpfs
+(for example, when using POSIX shared memory interface documented in
+.BR shm_overview (7)).
.SH EXAMPLE
.\" FIXME . Add an example here that uses an anonymous shared region for
.\" IPC between parent and child.
exit(EXIT_SUCCESS);
}
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR getpagesize (2),
.BR mincore (2),
.BR mlock (2),
.BR shmat (2),
.BR shm_open (3),
.BR shm_overview (7)
-.br
+
+The descriptions of the following files in
+.BR proc (5):
+.IR /proc/[pid]/maps ,
+.IR /proc/[pid]/map_files ,
+and
+.IR /proc/[pid]/smaps .
+
B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391.
.\"
.\" Repeat after me: private read-only mappings are 100% equivalent to