-.\" 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 2009-09-26 "Linux" "Linux Programmer's Manual"
+.TH MMAP 2 2014-08-19 "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.
.B MAP_GROWSDOWN
Used for stacks.
Indicates to the kernel virtual memory system that the mapping
-should extend downwards in memory.
+should extend downward in memory.
.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.
-.LP
-Of the above flags, only
-.B MAP_FIXED
-is specified in POSIX.1-2001.
-However, most systems also support
-.B MAP_ANONYMOUS
-(or its synonym
-.BR MAP_ANON ).
+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
.\" http://thread.gmane.org/gmane.linux.kernel/720412
.\" "pthread_create() slow for many threads; also time to revisit 64b
.\" context switch optimization?"
+.TP
+.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 honored only if the kernel was configured with the
+.B CONFIG_MMAP_ALLOW_UNINITIALIZED
+option.
+Because of the security implications,
+that option is normally enabled only on embedded devices
+(i.e., devices where one has complete control of the contents of user memory).
+.LP
+Of the above flags, only
+.B MAP_FIXED
+is specified in POSIX.1-2001.
+However, most systems also support
+.B MAP_ANONYMOUS
+(or its synonym
+.BR MAP_ANON ).
.LP
Some systems document the additional flags
.BR MAP_AUTOGROW ,
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.
.TP
.B EACCES
A file descriptor refers to a non-regular file.
-Or
-.B MAP_PRIVATE
-was requested, but
+Or a file mapping was requested, but
.I fd
is not open for reading.
Or
.\" A file could not be mapped for reading.
.TP
.B ENODEV
-The underlying file system of the specified file does not support
+The underlying filesystem of the specified file does not support
memory mapping.
.TP
.B ENOMEM
.I prot
argument asks for
.B PROT_EXEC
-but the mapped area belongs to a file on a file system that
+but the mapped area belongs to a file on a filesystem that
was mounted no-exec.
.\" (Since 2.4.25 / 2.6.0.)
.TP
+.B EPERM
+The operation was prevented by a file seal; see
+.BR fcntl (2).
+.TP
.B ETXTBSY
.B MAP_DENYWRITE
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.
.SH AVAILABILITY
On POSIX systems on which
.BR mmap (),
-.BR msync (2)
+.BR msync (2),
and
.BR munmap ()
are available,
.\" -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,
-.\" Since around glibc 2.1/2.2, depending on the platform.
-the glibc
-.BR mmap ()
-wrapper function invokes
-.BR mmap2 (2)
-with a suitably adjusted value for
-.IR offset .
-
On some hardware architectures (e.g., i386),
.B PROT_WRITE
implies
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 .
+.\"
+.SS C library/kernel ABI differences
+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 ()
+wrapper function invokes
+.BR mmap2 (2)
+with a suitably adjusted value for
+.IR offset .
.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.
pages of the file and then uses
.BR write (2)
to output the desired bytes.
+.SS Program source
.nf
-
#include <sys/mman.h>
#include <sys/stat.h>
#include <fcntl.h>
}
exit(EXIT_SUCCESS);
-} /* main */
+}
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR getpagesize (2),
+.BR memfd_create (2),
.BR mincore (2),
.BR mlock (2),
.BR mmap2 (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