diff options
Diffstat (limited to 'man2/remap_file_pages.2')
| -rw-r--r-- | man2/remap_file_pages.2 | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/man2/remap_file_pages.2 b/man2/remap_file_pages.2 new file mode 100644 index 0000000..ab4ee51 --- /dev/null +++ b/man2/remap_file_pages.2 @@ -0,0 +1,170 @@ +.\" Copyright (C) 2003, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +remap_file_pages \- create a nonlinear file mapping +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include <sys/mman.h> +.PP +.BI "[[deprecated]] int remap_file_pages(void " addr [. size "], size_t " size , +.BI " int " prot ", size_t " pgoff ", \ +int " flags ); +.fi +.SH DESCRIPTION +.BR Note : +.\" commit 33041a0d76d3c3e0aff28ac95a2ffdedf1282dbc +.\" http://lwn.net/Articles/597632/ +this system call was marked as deprecated starting with Linux 3.16. +In Linux 4.0, the implementation was replaced +.\" commit c8d78c1823f46519473949d33f0d1d33fe21ea16 +by a slower in-kernel emulation. +Those few applications that use this system call should +consider migrating to alternatives. +This change was made because the kernel code for this system call was complex, +and it is believed to be little used or perhaps even completely unused. +While it had some use cases in database applications on 32-bit systems, +those use cases don't exist on 64-bit systems. +.PP +The +.BR remap_file_pages () +system call is used to create a nonlinear mapping, that is, a mapping +in which the pages of the file are mapped into a nonsequential 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. +.PP +To create a nonlinear mapping we perform the following steps: +.TP 3 +1. +Use +.BR mmap (2) +to create a mapping (which is initially linear). +This mapping must be created with the +.B MAP_SHARED +flag. +.TP +2. +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. +.PP +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. +.PP +The +.I addr +argument serves two purposes. +First, it identifies the mapping whose pages we want to rearrange. +Thus, +.I addr +must be an address that falls within +a region previously mapped by a call to +.BR mmap (2). +Second, +.I addr +specifies the address at which the file pages +identified by +.I pgoff +and +.I size +will be placed. +.PP +The values specified in +.I addr +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 +.PP +The +.I prot +argument must be specified as 0. +.PP +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 to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I addr +does not refer to a valid mapping +created with the +.B MAP_SHARED +flag. +.TP +.B EINVAL +.IR addr , +.IR size , +.IR prot , +or +.I pgoff +is invalid. +.\" And possibly others from vma->vm_ops->populate() +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5.46, +glibc 2.3.3. +.SH NOTES +Since Linux 2.6.23, +.\" commit 3ee6dafc677a68e461a7ddafc94a580ebab80735 +.BR remap_file_pages () +creates non-linear mappings only +on in-memory filesystems such as +.BR tmpfs (5), +hugetlbfs or ramfs. +On filesystems with a backing store, +.BR remap_file_pages () +is not much more efficient than using +.BR mmap (2) +to adjust which parts of the file are mapped to which addresses. +.SH SEE ALSO +.BR getpagesize (2), +.BR mmap (2), +.BR mmap2 (2), +.BR mprotect (2), +.BR mremap (2), +.BR msync (2) |