1 files changed, 174 insertions, 0 deletions
diff --git a/man/man2/migrate_pages.2 b/man/man2/migrate_pages.2
new file mode 100644
index 000000000..3e96f0322
--- /dev/null
+++ b/man/man2/migrate_pages.2
@@ -0,0 +1,174 @@
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft-2-para
+.\"
+.\" Copyright 2009 Intel Corporation
+.\"                Author: Andi Kleen
+.\" Based on the move_pages manpage which was
+.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
+.\"                               Christoph Lameter
+.\"
+.TH migrate_pages 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+migrate_pages \- move all pages in a process to another set of nodes
+.SH LIBRARY
+NUMA (Non-Uniform Memory Access) policy library
+.RI ( libnuma ", " \-lnuma )
+.SH SYNOPSIS
+.nf
+.B #include <numaif.h>
+.P
+.BI "long migrate_pages(int " pid ", unsigned long " maxnode,
+.BI "                   const unsigned long *" old_nodes,
+.BI "                   const unsigned long *" new_nodes );
+.fi
+.SH DESCRIPTION
+.BR migrate_pages ()
+attempts to move all pages of the process
+.I pid
+that are in memory nodes
+.I old_nodes
+to the memory nodes in
+.IR new_nodes .
+Pages not located in any node in
+.I old_nodes
+will not be migrated.
+As far as possible,
+the kernel maintains the relative topology relationship inside
+.I old_nodes
+during the migration to
+.IR new_nodes .
+.P
+The
+.I old_nodes
+and
+.I new_nodes
+arguments are pointers to bit masks of node numbers, with up to
+.I maxnode
+bits in each mask.
+These masks are maintained as arrays of unsigned
+.I long
+integers (in the last
+.I long
+integer, the bits beyond those specified by
+.I maxnode
+are ignored).
+The
+.I maxnode
+argument is the maximum node number in the bit mask plus one (this is the same
+as in
+.BR mbind (2),
+but different from
+.BR select (2)).
+.P
+The
+.I pid
+argument is the ID of the process whose pages are to be moved.
+To move pages in another process,
+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.
+If
+.I pid
+is 0, then
+.BR migrate_pages ()
+moves pages of the calling process.
+.P
+Pages shared with another process will be moved only if the initiating
+process has the
+.B CAP_SYS_NICE
+privilege.
+.SH RETURN VALUE
+On success
+.BR migrate_pages ()
+returns the number of pages that could not be moved
+(i.e., a return of zero means that all pages were successfully moved).
+On error, it returns \-1, and sets
+.I errno
+to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+Part or all of the memory range specified by
+.IR old_nodes / new_nodes
+and
+.I maxnode
+points outside your accessible address space.
+.TP
+.B EINVAL
+The value specified by
+.I maxnode
+exceeds a kernel-imposed limit.
+.\" As at 3.5, this limit is "a page worth of bits", e.g.,
+.\" 8 * 4096 bits, assuming a 4kB page size.
+Or,
+.I old_nodes
+or
+.I new_nodes
+specifies one or more node IDs that are
+greater than the maximum supported node ID.
+Or, none of the node IDs specified by
+.I new_nodes
+are on-line and allowed by the process's current cpuset context,
+or none of the specified nodes contain memory.
+.TP
+.B EPERM
+Insufficient privilege
+.RB ( CAP_SYS_NICE )
+to move pages of the process specified by
+.IR pid ,
+or insufficient privilege
+.RB ( CAP_SYS_NICE )
+to access the specified target nodes.
+.TP
+.B ESRCH
+No process matching
+.I pid
+could be found.
+.\" FIXME Document the other errors that can occur for migrate_pages()
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.16.
+.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
+the calling process's cpuset.
+Note that this information is subject to change at any
+time by manual or automatic reconfiguration of the cpuset.
+.P
+Use of
+.BR migrate_pages ()
+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 migrate_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)
+.P
+.I Documentation/vm/page_migration.rst
+in the Linux kernel source tree