mirror of https://github.com/mkerrisk/man-pages
490 lines
13 KiB
Groff
490 lines
13 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl>
|
|
.\" and Copyright (C) 2006 Michael Kerrisk <mtk-manpages@gmx.net>
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
|
|
.\" Modified 2000-03-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
|
|
.\" Modified 2001-10-04 by John Levon <moz@compsoc.man.ac.uk>
|
|
.\" Modified 2003-02-02 by Andi Kleen <ak@muc.de>
|
|
.\" Modified 2003-05-21 by Michael Kerrisk <mtk-manpages@gmx.net>
|
|
.\" MAP_LOCKED works from 2.5.37
|
|
.\" Modified 2004-06-17 by Michael Kerrisk <mtk-manpages@gmx.net>
|
|
.\" Modified 2004-09-11 by aeb
|
|
.\" Modified 2004-12-08, from Eric Estievenart <eric.estievenart@free.fr>
|
|
.\" Modified 2004-12-08, mtk, formatting tidy-ups
|
|
.\" Modified 2006-12-04, mtk, various parts rewritten
|
|
.\"
|
|
.TH MMAP 2 2006-12-04 "Linux 2.6.19" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
mmap, munmap \- map or unmap files or devices into memory
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/mman.h>
|
|
.sp
|
|
.BI "void *mmap(void *" start ", size_t " length \
|
|
", int " prot ", int " flags ,
|
|
.BI " int " fd ", off_t " offset );
|
|
.sp
|
|
.BI "int munmap(void *" start ", size_t " length );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.BR mmap ()
|
|
creates a new mapping in the virtual address space of
|
|
the calling process.
|
|
The starting address for the new mapping is specified in
|
|
.IR start .
|
|
The
|
|
.I length
|
|
argument specifies the length of the mapping.
|
|
|
|
If
|
|
.I start
|
|
is NULL,
|
|
then the kernel chooses the address at which to create the mapping;
|
|
this is the most portable method of creating a new mapping.
|
|
If
|
|
.I start
|
|
is not NULL,
|
|
then the kernel takes it as a hint about where to place the mapping;
|
|
on Linux, the mapping will be created at the next higher page boundary.
|
|
The address of the new mapping is returned as the result of the call.
|
|
|
|
The contents of a file mapping (as opposed to an anonymous mapping; see
|
|
.B MAP_ANONYMOUS
|
|
below), are initialised using
|
|
.I length
|
|
bytes starting at offset
|
|
.I offset
|
|
in the file (or other object) referred to by the file descriptor
|
|
.IR fd .
|
|
.I offset
|
|
must be a multiple of the page size as returned by
|
|
.IR sysconf(_SC_PAGE_SIZE) .
|
|
.LP
|
|
The
|
|
.I prot
|
|
argument describes the desired memory protection of the mapping
|
|
(and must not conflict with the open mode of the file).
|
|
It is either
|
|
.B PROT_NONE
|
|
or the bitwise OR of one or more of the following flags:
|
|
.TP 1.1i
|
|
.B PROT_EXEC
|
|
Pages may be executed.
|
|
.TP
|
|
.B PROT_READ
|
|
Pages may be read.
|
|
.TP
|
|
.B PROT_WRITE
|
|
Pages may be written.
|
|
.TP
|
|
.B PROT_NONE
|
|
Pages may not be accessed.
|
|
.LP
|
|
The
|
|
.I flags
|
|
argument determines whether updates to the mapping
|
|
are visible to other processes mapping the same region,
|
|
and whether updates are caried through to the underlying file.
|
|
This behaviour is determined by including exactly one
|
|
of the following values in
|
|
.IR flags :
|
|
.TP 1.1i
|
|
.B MAP_SHARED
|
|
Share this mapping.
|
|
Updates to the mapping are visible to other processes that map this file,
|
|
and are carried through to the underlying file.
|
|
The file may not actually be updated until
|
|
.BR msync (2)
|
|
or
|
|
.BR munmap (2)
|
|
is called.
|
|
.TP
|
|
.B MAP_PRIVATE
|
|
Create a private copy-on-write mapping.
|
|
Updates to the mapping are not visible to other processes
|
|
mapping the same file, and are not carried through to
|
|
the underlying file.
|
|
It is unspecified whether changes made to the file after the
|
|
.BR mmap ()
|
|
call are visible in the mapped region.
|
|
.LP
|
|
Both of these flags are described in POSIX.1-2001.
|
|
|
|
In addition, zero or more of the following values can be ORed in
|
|
.IR flags :
|
|
.\" FIXME ? Place the following list in alphabetical order?
|
|
.TP
|
|
.B MAP_FIXED
|
|
Don't interpret
|
|
.I start
|
|
as a hint: place the mapping at exactly that address.
|
|
.I start
|
|
must be a multiple of the page size.
|
|
If the memory region specified by
|
|
.I start
|
|
and
|
|
.I len
|
|
overlaps pages of any existing mapping(s), then the overlapped
|
|
part of the existing mapping(s) will be discarded.
|
|
If the specified address cannot be used,
|
|
.BR mmap ()
|
|
will fail.
|
|
Because requiring a fixed address for a mapping is less portable,
|
|
the use of this option is discouraged.
|
|
.TP
|
|
.B MAP_DENYWRITE
|
|
This flag is ignored.
|
|
.\" Introduced in 1.1.36, removed in 1.3.24.
|
|
(Long ago, it signalled that attempts to write to the underlying file
|
|
should fail with
|
|
.BR ETXTBUSY .
|
|
But this was a source of denial-of-service attacks.)
|
|
.TP
|
|
.B MAP_EXECUTABLE
|
|
This flag is ignored.
|
|
.\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link.
|
|
.\" (Long ago, it signalled that the underlying file is an executable.
|
|
.\" However, that information was not really used anywhere.)
|
|
.\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of
|
|
.\" MAP_DENYWRITE?
|
|
.TP
|
|
.B MAP_NORESERVE
|
|
Do not reserve swap space for this mapping.
|
|
When swap space is reserved, one has the guarantee
|
|
that it is possible to modify the mapping.
|
|
When swap space is not reserved one might get SIGSEGV upon a write
|
|
if no physical memory is available.
|
|
See also the discussion of the file
|
|
.I /proc/sys/vm/overcommit_memory
|
|
in
|
|
.BR proc (5).
|
|
In kernels before 2.6, this flag only had effect for
|
|
private writable mappings.
|
|
.TP
|
|
.BR MAP_LOCKED " (since Linux 2.5.37)"
|
|
Lock the pages of the mapped region into memory in the manner of
|
|
.BR mlock () .
|
|
This flag is ignored in older kernels.
|
|
.\" If set, the mapped pages will not be swapped out.
|
|
.TP
|
|
.B MAP_GROWSDOWN
|
|
Used for stacks.
|
|
Indicates to the kernel virtual memory system that the mapping
|
|
should extend downwards in memory.
|
|
.TP
|
|
.B MAP_ANON
|
|
Synonym for
|
|
.BR MAP_ANONYMOUS .
|
|
Deprecated.
|
|
.TP
|
|
.B MAP_ANONYMOUS
|
|
The mapping is not backed by any file;
|
|
its contents are initialised to zero.
|
|
The
|
|
.I fd
|
|
and
|
|
.I offset
|
|
arguments are ignored;
|
|
however, some implementations require
|
|
.I fd
|
|
to be \-1 if
|
|
.B MAP_ANONYMOUS
|
|
(or
|
|
.BR MAP_ANON )
|
|
is specified,
|
|
and portable applications should ensure this.
|
|
The use of
|
|
.B MAP_ANONYMOUS
|
|
in conjunction with
|
|
.B MAP_SHARED
|
|
is only supported on Linux since kernel 2.4.
|
|
.TP
|
|
.B MAP_FILE
|
|
Compatibility flag.
|
|
Ignored.
|
|
.TP
|
|
.B MAP_32BIT
|
|
Put the mapping into the first 2GB of the process address space.
|
|
Ignored when
|
|
.B MAP_FIXED
|
|
is set.
|
|
This flag is currently only supported on x86-64 for 64bit programs.
|
|
.TP
|
|
.BR MAP_POPULATE " (since Linux 2.5.46)"
|
|
Populate (prefault) page tables for a file mapping,
|
|
by performing read-ahead on the file.
|
|
Later accesses to the mapping will not be blocked by page faults.
|
|
.TP
|
|
.BR MAP_NONBLOCK " (since Linux 2.5.46)"
|
|
Only meaningful in conjunction with
|
|
.BR MAP_POPULATE .
|
|
Don't perform read-ahead:
|
|
only create page tables entries for pages
|
|
that are already present in RAM.
|
|
.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 MAP_AUTOGROW, MAP_AUTORESRV,
|
|
MAP_COPY, and MAP_LOCAL.
|
|
.LP
|
|
Memory mapped by
|
|
.BR mmap ()
|
|
is preserved across
|
|
.BR fork (2),
|
|
with the same attributes.
|
|
.LP
|
|
A file is mapped in multiples of the page size.
|
|
For a file that is not
|
|
a multiple of the page size, the remaining memory is zeroed when mapped,
|
|
and writes to that region are not written out to the file.
|
|
The effect of
|
|
changing the size of the underlying file of a mapping on the pages that
|
|
correspond to added or removed regions of the file is unspecified.
|
|
|
|
The
|
|
.BR munmap ()
|
|
system call deletes the mappings for the specified address range, and
|
|
causes further references to addresses within the range to generate
|
|
invalid memory references.
|
|
The region is also automatically unmapped
|
|
when the process is terminated.
|
|
On the other hand, closing the file
|
|
descriptor does not unmap the region.
|
|
.LP
|
|
The address
|
|
.I start
|
|
must be a multiple of the page size.
|
|
All pages containing a part
|
|
of the indicated range are unmapped, and subsequent references
|
|
to these pages will generate SIGSEGV.
|
|
It is not an error if the
|
|
indicated range does not contain any mapped pages.
|
|
|
|
For file-backed mappings, the
|
|
.I st_atime
|
|
field for the mapped file may be updated at any time between the
|
|
.BR mmap ()
|
|
and the corresponding unmapping; the first reference to a mapped
|
|
page will update the field if it has not been already.
|
|
.LP
|
|
The
|
|
.I st_ctime
|
|
and
|
|
.I st_mtime
|
|
field for a file mapped with
|
|
.B PROT_WRITE
|
|
and
|
|
.B MAP_SHARED
|
|
will be updated after
|
|
a write to the mapped region, and before a subsequent
|
|
.BR msync ()
|
|
with the
|
|
.B MS_SYNC
|
|
or
|
|
.BR MS_ASYNC
|
|
flag, if one occurs.
|
|
.SH "RETURN VALUE"
|
|
On success,
|
|
.BR mmap ()
|
|
returns a pointer to the mapped area.
|
|
On error, the value
|
|
.B MAP_FAILED
|
|
(that is,
|
|
.I "(void *) \-1)"
|
|
is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
On success,
|
|
.BR munmap ()
|
|
returns 0, on failure \-1, and
|
|
.I errno
|
|
is set (probably to
|
|
.BR EINVAL ).
|
|
.SH NOTES
|
|
It is architecture dependent whether
|
|
.B PROT_READ
|
|
implies
|
|
.B PROT_EXEC
|
|
or not.
|
|
Portable programs should always set
|
|
.B PROT_EXEC
|
|
if they intend to execute code in the new mapping.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EACCES
|
|
A file descriptor refers to a non-regular file.
|
|
Or
|
|
.B MAP_PRIVATE
|
|
was requested, but
|
|
.I fd
|
|
is not open for reading.
|
|
Or
|
|
.B MAP_SHARED
|
|
was requested and
|
|
.B PROT_WRITE
|
|
is set, but
|
|
.I fd
|
|
is not open in read/write (O_RDWR) mode.
|
|
Or
|
|
.B PROT_WRITE
|
|
is set, but the file is append-only.
|
|
.TP
|
|
.B EAGAIN
|
|
The file has been locked, or too much memory has been locked (see
|
|
.BR setrlimit (2)).
|
|
.TP
|
|
.B EBADF
|
|
.I fd
|
|
is not a valid file descriptor (and
|
|
.B MAP_ANONYMOUS
|
|
was not set).
|
|
.TP
|
|
.B EINVAL
|
|
We don't like
|
|
.IR start ,
|
|
.IR length ,
|
|
or
|
|
.IR offset
|
|
(e.g., they are too large, or not aligned on a page boundary).
|
|
.TP
|
|
.B EINVAL
|
|
(since Linux 2.6.12),
|
|
.I length
|
|
was 0.
|
|
.TP
|
|
.B EINVAL
|
|
.I flags
|
|
contained neither
|
|
.B MAP_PRIVATE
|
|
or
|
|
.BR MAP_SHARED ,
|
|
or contained both of these values.
|
|
.TP
|
|
.B ENFILE
|
|
.\" This is for shared anonymous segments
|
|
.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
|
|
The system limit on the total number of open files has been reached.
|
|
.\" .TP
|
|
.\" .B ENOEXEC
|
|
.\" A file could not be mapped for reading.
|
|
.TP
|
|
.B ENODEV
|
|
The underlying filesystem of the specified file does not support
|
|
memory mapping.
|
|
.TP
|
|
.B ENOMEM
|
|
No memory is available, or the process's maximum number of mappings would
|
|
have been exceeded.
|
|
.TP
|
|
.B EPERM
|
|
The
|
|
.I prot
|
|
argument asks for
|
|
.B PROT_EXEC
|
|
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 ETXTBSY
|
|
.B MAP_DENYWRITE
|
|
was set but the object specified by
|
|
.I fd
|
|
is open for writing.
|
|
.LP
|
|
Use of a mapped region can result in these signals:
|
|
.TP
|
|
.B SIGSEGV
|
|
Attempted write into a region mapped as read-only.
|
|
.TP
|
|
.B SIGBUS
|
|
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 AVAILABILITY
|
|
On POSIX systems on which
|
|
.BR mmap (),
|
|
.BR msync ()
|
|
and
|
|
.BR munmap ()
|
|
are available,
|
|
.B _POSIX_MAPPED_FILES
|
|
is defined in <unistd.h> to a value greater than 0. (See also
|
|
.BR sysconf (3).)
|
|
.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
|
|
.\" -1: unavailable, 0: ask using sysconf().
|
|
.\" glibc defines it to 1.
|
|
.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 BUGS
|
|
On Linux there are no guarantees like those suggested above under
|
|
.BR MAP_NORESERVE .
|
|
By default, any process can be killed
|
|
at any moment when the system runs out of memory.
|
|
|
|
In kernels before 2.6.7, the
|
|
.B MAP_POPULATE
|
|
flag only has effect if
|
|
.I prot
|
|
is specified as
|
|
.BR PROT_NONE .
|
|
|
|
SUSv3 specifies that
|
|
.BR mmap ()
|
|
should fail if
|
|
.I length
|
|
is 0.
|
|
However, in kernels before 2.6.12,
|
|
.BR mmap ()
|
|
succeeded in this case: no mapping was created and the call returned
|
|
.IR start .
|
|
Since kernel 2.6.12,
|
|
.BR mmap ()
|
|
fails with the error
|
|
.B EINVAL
|
|
for this case.
|
|
.SH "SEE ALSO"
|
|
.BR getpagesize (2),
|
|
.BR mincore (2),
|
|
.BR mlock (2),
|
|
.BR mmap2 (2),
|
|
.BR mremap (2),
|
|
.BR msync (2),
|
|
.BR remap_file_pages (2),
|
|
.BR setrlimit (2),
|
|
.BR shm_open (3)
|
|
.br
|
|
B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391.
|
|
.\"
|
|
.\" Repeat after me: private read-only mappings are 100% equivalent to
|
|
.\" shared read-only mappings. No ifs, buts, or maybes. -- Linus
|