Merging upstream version 6.8.

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

1 files changed, 253 insertions, 0 deletions

diff --git a/man/man2/move_pages.2 b/man/man2/move_pages.2
new file mode 100644
index 0000000..c6b7349
--- /dev/null
+++ b/man/man2/move_pages.2
@@ -0,0 +1,253 @@
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
+.\"                               Christoph Lameter
+.\"
+.\" FIXME Should programs normally be using move_pages() directly, or should
+.\" they rather be using interfaces in the numactl package?
+.\" (e.g., compare with recommendation in mbind(2)).
+.\" Does this page need to give advice on this topic?
+.\"
+.TH move_pages 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+move_pages \- move individual pages of a process to another node
+.SH LIBRARY
+NUMA (Non-Uniform Memory Access) policy library
+.RI ( libnuma ", " \-lnuma )
+.SH SYNOPSIS
+.nf
+.B #include <numaif.h>
+.P
+.BI "long move_pages(int " pid ", unsigned long " count ", \
+void *" pages [. count ],
+.BI "                const int " nodes [. count "], int " status [. count "], \
+int " flags );
+.fi
+.SH DESCRIPTION
+.BR move_pages ()
+moves the specified
+.I pages
+of the process
+.I pid
+to the memory nodes specified by
+.IR nodes .
+The result of the move is reflected in
+.IR status .
+The
+.I flags
+indicate constraints on the pages to be moved.
+.P
+.I pid
+is the ID of the process in which pages are to be moved.
+If
+.I pid
+is 0, then
+.BR move_pages ()
+moves pages of the calling process.
+.P
+To move pages in another process requires the following privileges:
+.IP \[bu] 3
+Up to and including Linux 4.12:
+the caller must be privileged
+.RB ( CAP_SYS_NICE )
+or the real or effective user ID of the calling process must match the
+real or saved-set user ID of the target process.
+.IP \[bu]
+The older rules allowed the caller to discover various
+virtual address choices made by the kernel that could lead
+to the defeat of address-space-layout randomization
+for a process owned by the same UID as the caller,
+the rules were changed starting with Linux 4.13.
+Since Linux 4.13,
+.\" commit 197e7e521384a23b9e585178f3f11c9fa08274b9
+permission is governed by a ptrace access mode
+.B PTRACE_MODE_READ_REALCREDS
+check with respect to the target process; see
+.BR ptrace (2).
+.P
+.I count
+is the number of pages to move.
+It defines the size of the three arrays
+.IR pages ,
+.IR nodes ,
+and
+.IR status .
+.P
+.I pages
+is an array of pointers to the pages that should be moved.
+These are pointers that should be aligned to page boundaries.
+.\" FIXME Describe the result if pointers in the 'pages' array are
+.\" not aligned to page boundaries
+Addresses are specified as seen by the process specified by
+.IR pid .
+.P
+.I nodes
+is an array of integers that specify the desired location for each page.
+Each element in the array is a node number.
+.I nodes
+can also be NULL, in which case
+.BR move_pages ()
+does not move any pages but instead will return the node
+where each page currently resides, in the
+.I status
+array.
+Obtaining the status of each page may be necessary to determine
+pages that need to be moved.
+.P
+.I status
+is an array of integers that return the status of each page.
+The array contains valid values only if
+.BR move_pages ()
+did not return an error.
+Preinitialization of the array to a value
+which cannot represent a real numa node or valid error of status array
+could help to identify pages that have been migrated.
+.P
+.I flags
+specify what types of pages to move.
+.B MPOL_MF_MOVE
+means that only pages that are in exclusive use by the process
+are to be moved.
+.B MPOL_MF_MOVE_ALL
+means that pages shared between multiple processes can also be moved.
+The process must be privileged
+.RB ( CAP_SYS_NICE )
+to use
+.BR MPOL_MF_MOVE_ALL .
+.SS Page states in the status array
+The following values can be returned in each element of the
+.I status
+array.
+.TP
+.B 0..MAX_NUMNODES
+Identifies the node on which the page resides.
+.TP
+.B \-EACCES
+The page is mapped by multiple processes and can be moved only if
+.B MPOL_MF_MOVE_ALL
+is specified.
+.TP
+.B \-EBUSY
+The page is currently busy and cannot be moved.
+Try again later.
+This occurs if a page is undergoing I/O or another kernel subsystem
+is holding a reference to the page.
+.TP
+.B \-EFAULT
+This is a zero page or the memory area is not mapped by the process.
+.TP
+.B \-EIO
+Unable to write back a page.
+The page has to be written back
+in order to move it since the page is dirty and the filesystem
+does not provide a migration function that would allow the move
+of dirty pages.
+.TP
+.B \-EINVAL
+A dirty page cannot be moved.
+The filesystem does not
+provide a migration function and has no ability to write back pages.
+.TP
+.B \-ENOENT
+The page is not present.
+.TP
+.B \-ENOMEM
+Unable to allocate memory on target node.
+.SH RETURN VALUE
+On success
+.BR move_pages ()
+returns zero.
+.\" FIXME . Is the following quite true: does the wrapper in numactl
+.\" do the right thing?
+On error, it returns \-1, and sets
+.I errno
+to indicate the error.
+If positive value is returned, it is the number of
+nonmigrated pages.
+.SH ERRORS
+.TP
+.B Positive value
+The number of nonmigrated pages if they were the result of nonfatal
+reasons (since
+.\" commit a49bd4d7163707de377aee062f17befef6da891b
+Linux 4.17).
+.TP
+.B E2BIG
+Too many pages to move.
+Since Linux 2.6.29,
+.\" commit 3140a2273009c01c27d316f35ab76a37e105fdd8
+the kernel no longer generates this error.
+.TP
+.B EACCES
+.\" FIXME Clarify "current cpuset" in the description of the EACCES error.
+.\" Is that the cpuset of the caller or the target?
+One of the target nodes is not allowed by the current cpuset.
+.TP
+.B EFAULT
+Parameter array could not be accessed.
+.TP
+.B EINVAL
+Flags other than
+.B MPOL_MF_MOVE
+and
+.B MPOL_MF_MOVE_ALL
+was specified or an attempt was made to migrate pages of a kernel thread.
+.TP
+.B ENODEV
+One of the target nodes is not online.
+.TP
+.B EPERM
+The caller specified
+.B MPOL_MF_MOVE_ALL
+without sufficient privileges
+.RB ( CAP_SYS_NICE ).
+Or, the caller attempted to move pages of a process belonging
+to another user but did not have privilege to do so
+.RB ( CAP_SYS_NICE ).
+.TP
+.B ESRCH
+Process does not exist.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.18.
+.SH NOTES
+For information on library support, see
+.BR numa (7).
+.P
+Use
+.BR get_mempolicy (2)
+with the
+.B MPOL_F_MEMS_ALLOWED
+flag to obtain the set of nodes that are allowed by
+.\" FIXME Clarify "current cpuset".  Is that the cpuset of the caller
+.\" or the target?
+the current cpuset.
+Note that this information is subject to change at any
+time by manual or automatic reconfiguration of the cpuset.
+.P
+Use of this function may result in pages whose location
+(node) violates the memory policy established for the
+specified addresses (See
+.BR mbind (2))
+and/or the specified process (See
+.BR set_mempolicy (2)).
+That is, memory policy does not constrain the destination
+nodes used by
+.BR move_pages ().
+.P
+The
+.I <numaif.h>
+header is not included with glibc, but requires installing
+.I libnuma\-devel
+or a similar package.
+.SH SEE ALSO
+.BR get_mempolicy (2),
+.BR mbind (2),
+.BR set_mempolicy (2),
+.BR numa (3),
+.BR numa_maps (5),
+.BR cpuset (7),
+.BR numa (7),
+.BR migratepages (8),
+.BR numastat (8)