Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 170 insertions, 0 deletions

diff --git a/man/man2/remap_file_pages.2 b/man/man2/remap_file_pages.2
new file mode 100644
index 0000000..3caf9af
--- /dev/null
+++ b/man/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 2024-05-02 "Linux man-pages (unreleased)"
+.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>
+.P
+.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.
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+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
+.P
+The
+.I prot
+argument must be specified as 0.
+.P
+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)