mirror of https://github.com/mkerrisk/man-pages
Documentation of the move_pages() system call.
This page was formerly part of the numactl package, but really belongs in man-pages (since it describes a kernel interface).
This commit is contained in:
parent
5b7257a6e5
commit
abe7c8711b
|
@ -0,0 +1,217 @@
|
|||
.\" Hey Emacs! This file is -*- nroff -*- source.
|
||||
.\"
|
||||
.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
|
||||
.\" Christoph Lameter
|
||||
.\"
|
||||
.\" 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.
|
||||
.\"
|
||||
.\" FIXME Should programs normally be using this API directly, or should
|
||||
.\" they rather be using interfaces in the numactl package?
|
||||
.\" (e.g., compare with recommendation in mbind(2)).
|
||||
.TH MOVE_PAGES 2 2008-08-12 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
move_pages \- move individual pages of a process to another node
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.B #include <numaif.h>
|
||||
.sp
|
||||
.BI "long move_pages(int " pid ", unsigned long count, void **" pages ,
|
||||
.BI " const int *" nodes ", int *" status ", 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.
|
||||
|
||||
.I pid
|
||||
is the ID of the process in which 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 move_pages ()
|
||||
moves pages of the calling process.
|
||||
|
||||
.I count
|
||||
is the number of pages to move.
|
||||
It defines the size of the three arrays
|
||||
.IR pages ,
|
||||
.IR nodes ,
|
||||
and
|
||||
.IR status .
|
||||
|
||||
.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 what if they are not aligned?
|
||||
Addresses are specified as seen by the process specified by
|
||||
.IR pid .
|
||||
|
||||
.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.
|
||||
|
||||
.I status
|
||||
is an array of integers that return the status of each page.
|
||||
The array only contains valid values if
|
||||
.BR move_pages ()
|
||||
did not return an error.
|
||||
|
||||
.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 .
|
||||
.SH 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 only be moved 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.
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B E2BIG
|
||||
Too many pages to move.
|
||||
.TP
|
||||
.B EACCESS
|
||||
.\" FIXME Clarify "current cpuset". 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 ENOENT
|
||||
No pages were found that require moving.
|
||||
All pages are either already
|
||||
on the target node, not present, had an invalid address or could not be
|
||||
moved because they were mapped by multiple processes.
|
||||
.TP
|
||||
.B EPERM
|
||||
The caller specified
|
||||
.B MPOL_MF_MOVE_ALL
|
||||
without sufficient privileges
|
||||
.RB ( CAP_SYS_NICE ).
|
||||
Or, the caller attempted to move 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 "NOTES"
|
||||
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.
|
||||
|
||||
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 ().
|
||||
.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 migratepages (8),
|
||||
.BR numa_stat (8)
|
Loading…
Reference in New Issue