1 .\" Hey Emacs! This file is -*- nroff -*- source.
3 .\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
15 .\" FIXME Should programs normally be using this API directly, or should
16 .\" they rather be using interfaces in the numactl package?
17 .\" (e.g., compare with recommendation in mbind(2)).
18 .TH MOVE_PAGES 2 2010-06-11 "Linux" "Linux Programmer's Manual"
20 move_pages \- move individual pages of a process to another node
23 .B #include <numaif.h>
25 .BI "long move_pages(int " pid ", unsigned long count, void **" pages ,
26 .BI " const int *" nodes ", int *" status ", int " flags );
29 Link with \fI\-lnuma\fP.
36 to the memory nodes specified by
38 The result of the move is reflected in
42 indicate constraints on the pages to be moved.
45 is the ID of the process in which pages are to be moved.
46 To move pages in another process,
47 the caller must be privileged
49 or the real or effective user ID of the calling process must match the
50 real or saved-set user ID of the target process.
55 moves pages of the calling process.
58 is the number of pages to move.
59 It defines the size of the three arrays
66 is an array of pointers to the pages that should be moved.
67 These are pointers that should be aligned to page boundaries.
68 .\" FIXME what if they are not aligned?
69 Addresses are specified as seen by the process specified by
73 is an array of integers that specify the desired location for each page.
74 Each element in the array is a node number.
76 can also be NULL, in which case
78 does not move any pages but instead will return the node
79 where each page currently resides, in the
82 Obtaining the status of each page may be necessary to determine
83 pages that need to be moved.
86 is an array of integers that return the status of each page.
87 The array only contains valid values if
89 did not return an error.
92 specify what types of pages to move.
94 means that only pages that are in exclusive use by the process
97 means that pages shared between multiple processes can also be moved.
98 The process must be privileged
101 .BR MPOL_MF_MOVE_ALL .
102 .SH Page states in the status array
103 The following values can be returned in each element of the
108 Identifies the node on which the page resides.
111 The page is mapped by multiple processes and can only be moved if
116 The page is currently busy and cannot be moved.
118 This occurs if a page is undergoing I/O or another kernel subsystem
119 is holding a reference to the page.
122 This is a zero page or the memory area is not mapped by the process.
125 Unable to write back a page.
126 The page has to be written back
127 in order to move it since the page is dirty and the file system
128 does not provide a migration function that would allow the move
132 A dirty page cannot be moved.
133 The file system does not
134 provide a migration function and has no ability to write back pages.
137 The page is not present.
140 Unable to allocate memory on target node.
145 .\" FIXME Is the following quite true: does the wrapper in numactl
146 .\" do the right thing?
147 On error, it returns \-1, and sets
149 to indicate the error.
153 Too many pages to move.
156 .\" FIXME Clarify "current cpuset". Is that the cpuset of the caller
158 One of the target nodes is not allowed by the current cpuset.
161 Parameter array could not be accessed.
168 was specified or an attempt was made to migrate pages of a kernel thread.
171 One of the target nodes is not online.
174 No pages were found that require moving.
175 All pages are either already
176 on the target node, not present, had an invalid address or could not be
177 moved because they were mapped by multiple processes.
182 without sufficient privileges
183 .RB ( CAP_SYS_NICE ).
184 Or, the caller attempted to move pages of a process belonging
185 to another user but did not have privilege to do so
186 .RB ( CAP_SYS_NICE ).
189 Process does not exist.
192 first appeared on Linux in version 2.6.18.
194 This system call is Linux-specific.
196 For information on library support, see
200 .BR get_mempolicy (2)
202 .B MPOL_F_MEMS_ALLOWED
203 flag to obtain the set of nodes that are allowed by
204 .\" FIXME Clarify "current cpuset". Is that the cpuset of the caller
207 Note that this information is subject to change at any
208 time by manual or automatic reconfiguration of the cpuset.
210 Use of this function may result in pages whose location
211 (node) violates the memory policy established for the
212 specified addresses (See
214 and/or the specified process (See
215 .BR set_mempolicy (2)).
216 That is, memory policy does not constrain the destination
222 header is not included with glibc, but requires installing
224 or a similar package.
226 .BR get_mempolicy (2),
228 .BR set_mempolicy (2),
233 .BR migratepages (8),