mirror of https://github.com/mkerrisk/man-pages
160 lines
3.9 KiB
Groff
160 lines
3.9 KiB
Groff
.\" Copyright (C) 2003, Michael Kerrisk (mtk.manpages@gmail.com)
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" 2003-12-10 Initial creation, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" 2004-10-28 aeb, corrected prototype, prot must be 0
|
|
.\"
|
|
.TH REMAP_FILE_PAGES 2 2004-10-28 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
remap_file_pages \- create a non-linear file mapping
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #define _GNU_SOURCE
|
|
.B #include <sys/mman.h>
|
|
.sp
|
|
.BI "int remap_file_pages(void *" start ", size_t " size ", int " prot ,
|
|
.BI " ssize_t " pgoff ", int " flags );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR remap_file_pages ()
|
|
system call is used to create a non-linear mapping, that is, a mapping
|
|
in which the pages of the file are mapped into a non-sequential order
|
|
in memory.
|
|
The advantage of using
|
|
.BR remap_file_pages ()
|
|
over using repeated calls to
|
|
.BR mmap (2)
|
|
is that the former approach does not require the kernel to create
|
|
additional VMA (Virtual Memory Area) data structures.
|
|
|
|
To create a non-linear mapping we perform the following steps:
|
|
.TP
|
|
\fB1.\fP
|
|
Use
|
|
.BR mmap (2)
|
|
to create a mapping (which is initially linear).
|
|
This mapping must be created with the
|
|
.B MAP_SHARED
|
|
flag.
|
|
.TP
|
|
\fB2.\fP
|
|
Use one or more calls to
|
|
.BR remap_file_pages ()
|
|
to rearrange the correspondence between the pages of the mapping
|
|
and the pages of the file.
|
|
It is possible to map the same page of a file
|
|
into multiple locations within the mapped region.
|
|
.LP
|
|
The
|
|
.I pgoff
|
|
and
|
|
.I size
|
|
arguments specify the region of the file that is to be relocated
|
|
within the mapping:
|
|
.I pgoff
|
|
is a file offset in units of the system page size;
|
|
.I size
|
|
is the length of the region in bytes.
|
|
|
|
The
|
|
.I start
|
|
argument serves two purposes.
|
|
First, it identifies the mapping whose pages we want to rearrange.
|
|
Thus,
|
|
.I start
|
|
must be an address that falls within
|
|
a region previously mapped by a call to
|
|
.BR mmap (2).
|
|
Second,
|
|
.I start
|
|
specifies the address at which the file pages
|
|
identified by
|
|
.I pgoff
|
|
and
|
|
.I size
|
|
will be placed.
|
|
|
|
The values specified in
|
|
.I start
|
|
and
|
|
.I size
|
|
should be multiples of the system page size.
|
|
If they are not, then the kernel rounds
|
|
.I both
|
|
values
|
|
.I down
|
|
to the nearest multiple of the page size.
|
|
.\" This rounding is weird, and not consistent with the treatment of
|
|
.\" the analogous arguments for munmap()/mprotect() and for mlock().
|
|
.\" MTK, 14 Sep 2005
|
|
|
|
The
|
|
.I prot
|
|
argument must be specified as 0.
|
|
|
|
The
|
|
.I flags
|
|
argument has the same meaning as for
|
|
.BR mmap (2),
|
|
but all flags other than
|
|
.B MAP_NONBLOCK
|
|
are ignored.
|
|
.SH "RETURN VALUE"
|
|
On success,
|
|
.BR remap_file_pages ()
|
|
returns 0.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EINVAL
|
|
.I start
|
|
does not refer to a valid mapping
|
|
created with the
|
|
.B MAP_SHARED
|
|
flag.
|
|
.TP
|
|
.B EINVAL
|
|
.IR start ,
|
|
.IR size ,
|
|
.IR prot ,
|
|
or
|
|
.I pgoff
|
|
is invalid.
|
|
.\" And possibly others from vma->vm_ops->populate()
|
|
.SH VERSIONS
|
|
The
|
|
.BR remap_file_pages ()
|
|
system call appeared in Linux 2.5.46;
|
|
glibc support was added in version 2.3.3.
|
|
.SH "CONFORMING TO"
|
|
The
|
|
.BR remap_file_pages ()
|
|
system call is Linux specific.
|
|
.SH "SEE ALSO"
|
|
.BR getpagesize (2),
|
|
.BR mmap (2),
|
|
.BR mmap2 (2),
|
|
.BR mprotect (2),
|
|
.BR mremap (2),
|
|
.BR msync (2),
|
|
.BR feature_test_macros (7)
|