1NUMACTL(8)               Linux Administrator's Manual               NUMACTL(8)
2
3
4

NAME

6       numactl - Control NUMA policy for processes or shared memory
7

SYNOPSIS

9       numactl  [ --all ] [ --interleave nodes ] [ --preferred node ] [ --mem‐
10       bind nodes  ]  [  --cpunodebind  nodes  ]  [  --physcpubind  cpus  ]  [
11       --localalloc ] [--] command {arguments ...}
12       numactl --show
13       numactl --hardware
14       numactl [ --huge ] [ --offset offset ] [ --shmmode shmmode ] [ --length
15       length ] [ --strict ]
16       [ --shmid id ] --shm shmkeyfile | --file tmpfsfile
17       [ --touch ] [ --dump ] [ --dump-nodes ] memory policy
18

DESCRIPTION

20       numactl runs processes with a specific NUMA scheduling or memory place‐
21       ment policy.  The policy is set for command and inherited by all of its
22       children.  In addition it can set persistent policy for  shared  memory
23       segments or files.
24
25       Use  --  before command if using command options that could be confused
26       with numactl options.
27
28       nodes may be specified as N,N,N or  N-N or N,N-N  or   N-N,N-N  and  so
29       forth.  Relative nodes may be specifed as +N,N,N or  +N-N or +N,N-N and
30       so forth. The + indicates that the node numbers  are  relative  to  the
31       process'  set  of allowed nodes in its current cpuset.  A !N-N notation
32       indicates the inverse of N-N, in other words all nodes except N-N.   If
33       used  with + notation, specify !+N-N. When same is specified the previ‐
34       ous nodemask specified on the command line  is  used.   all  means  all
35       nodes in the current cpuset.
36
37       Instead of a number a node can also be:
38
39       netdev:DEV                 The node connected to network device DEV.
40       file:PATH                  The node the block device of PATH.
41       ip:HOST                    The node of the network device of HOST
42       block:PATH                 The node of block device PATH
43       pci:[seg:]bus:dev[:func]   The node of a PCI device.
44
45       Note  that  block  resolves the kernel block device names only for udev
46       names in /dev use file:
47
48       Policy settings are:
49
50       --all, -a
51              Unset default cpuset awareness, so user  can  use  all  possible
52              CPUs/nodes for following policy settings.
53
54       --interleave=nodes, -i nodes
55              Set  a  memory interleave policy. Memory will be allocated using
56              round robin on nodes.  When memory cannot be  allocated  on  the
57              current  interleave  target  fall back to other nodes.  Multiple
58              nodes may be specified on --interleave, --membind and --cpunode‐
59              bind.
60
61       --membind=nodes, -m nodes
62              Only  allocate  memory  from  nodes.   Allocation will fail when
63              there is not enough memory available on these nodes.  nodes  may
64              be specified as noted above.
65
66       --cpunodebind=nodes, -N nodes
67              Only  execute command on the CPUs of nodes.  Note that nodes may
68              consist of multiple CPUs.   nodes  may  be  specified  as  noted
69              above.
70
71       --physcpubind=cpus, -C cpus
72              Only execute process on cpus.  This accepts cpu numbers as shown
73              in the processor fields of /proc/cpuinfo, or relative cpus as in
74              relative  to  the  current cpuset.  You may specify "all", which
75              means all cpus in the current  cpuset.   Physical  cpus  may  be
76              specified  as  N,N,N  or  N-N or N,N-N or  N-N,N-N and so forth.
77              Relative cpus may be specifed as +N,N,N or  +N-N or  +N,N-N  and
78              so  forth.  The + indicates that the cpu numbers are relative to
79              the process' set of allowed cpus in its current cpuset.  A  !N-N
80              notation  indicates  the inverse of N-N, in other words all cpus
81              except N-N.  If used with + notation, specify !+N-N.
82
83       --localalloc, -l
84              Always allocate on the current node.
85
86       --preferred=node
87              Preferably allocate memory on node,  but  if  memory  cannot  be
88              allocated  there  fall  back  to other nodes.  This option takes
89              only a single node number.  Relative notation may be used.
90
91       --show, -s
92              Show NUMA policy settings of the current process.
93
94       --hardware, -H
95              Show inventory of available nodes on the system.
96
97       Numactl can set up policy for a SYSV shared memory segment or a file in
98       shmfs/hugetlbfs.
99
100       This  policy  is  persistent and will be used by all mappings from that
101       shared memory. The order of options matters  here.   The  specification
102       must  at  least include either of --shm, --shmid, --file to specify the
103       shared memory segment or file and a memory policy like described  above
104       ( --interleave, --localalloc, --preferred, --membind ).
105
106       --huge
107       When  creating a SYSV shared memory segment use huge pages.  Only valid
108       before --shmid or --shm
109
110       --offset
111       Specify offset into the shared memory segment. Default 0.  Valid  units
112       are m (for MB), g (for GB), k (for KB), otherwise it specifies bytes.
113
114       --strict
115       Give  an  error  when  a page in the policied area in the shared memory
116       segment already was faulted in with a conflicting policy. Default is to
117       silently ignore this.
118
119       --shmmode shmmode
120       Only  valid  before --shmid or --shm When creating a shared memory seg‐
121       ment set it to numeric mode shmmode.
122
123       --length length
124       Apply policy to length range in the shared memory segment or  make  the
125       segment  length  long  Default  is to use the remaining length Required
126       when a shared memory segment is created and specifies the length of the
127       new  segment  then. Valid units are m (for MB), g (for GB), k (for KB),
128       otherwise it specifies bytes.
129
130       --shmid id
131       Create or use an shared memory segment with numeric ID id
132
133       --shm shmkeyfile
134       Create or use an shared memory segment, with  the  ID  generated  using
135       ftok(3) from shmkeyfile
136
137       --file tmpfsfile
138       Set policy for a file in tmpfs or hugetlbfs
139
140       --touch
141       Touch  pages to enforce policy early. Default is to not touch them, the
142       policy is applied when an applications maps and accesses a page.
143
144       --dump
145       Dump policy in the specified range.
146
147       --dump-nodes
148       Dump all nodes of the specific range (very verbose!)
149
150       Valid node specifiers
151
152       all                 All nodes
153       number              Node number
154       number1{,number2}   Node number1 and Node number2
155       number1-number2     Nodes from number1 to number2
156       ! nodes             Invert selection of the following specification.
157

EXAMPLES

159       numactl --physcpubind=+0-4,8-12 myapplic arguments Run myapplic on cpus
160       0-4 and 8-12 of the current cpuset.
161
162       numactl  --interleave=all  bigdatabase  arguments Run big database with
163       its memory interleaved on all CPUs.
164
165       numactl --cpunodebind=0 --membind=0,1 process Run  process  on  node  0
166       with memory allocated on node 0 and 1.
167
168       numactl  --cpunodebind=0  --membind=0,1  --  process  -l Run process as
169       above, but with an option (-l) that would be confused  with  a  numactl
170       option.
171
172       numactl  --cpunodebind=netdev:eth0 --membind=netdev:eth0 network-server
173       Run network-server on the node of network device eth0 with  its  memory
174       also in the same node.
175
176       numactl  --preferred=1 numactl --show Set preferred node 1 and show the
177       resulting state.
178
179       numactl --interleave=all --shm /tmp/shmkey Interleave all of  the  sysv
180       shared memory region specified by /tmp/shmkey over all nodes.
181
182       Place a tmpfs file on 2 nodes:
183         numactl --membind=2 dd if=/dev/zero of=/dev/shm/A bs=1M count=1024
184         numactl  --membind=3  dd  if=/dev/zero  of=/dev/shm/A seek=1024 bs=1M
185       count=1024
186
187
188       numactl --localalloc /dev/shm/file Reset the policy for the shared mem‐
189       ory file file to the default localalloc policy.
190

NOTES

192       Requires an NUMA policy aware kernel.
193
194       Command  is  not  executed  using  a  shell.  If  you want to use shell
195       metacharacters in the child use sh -c as wrapper.
196
197       Setting policy for a hugetlbfs file does currently not work because  it
198       cannot be extended by truncate.
199
200       Shared  memory  segments  larger than numactl's address space cannot be
201       completely policied. This could be a problem  on  32bit  architectures.
202       Changing it piece by piece may work.
203
204       The  old --cpubind which accepts node numbers, not cpu numbers, is dep‐
205       recated and replaced  with  the  new  --cpunodebind  and  --physcpubind
206       options.
207
208

FILES

210       /proc/cpuinfo for the listing of active CPUs. See proc(5) for details.
211
212       /sys/devices/system/node/node*/numastat for NUMA memory hit statistics.
213
214
216       Copyright  2002,2004  Andi Kleen, SuSE Labs.  numactl and the demo pro‐
217       grams are under the GNU General Public License, v.2
218
219

SEE ALSO

221       set_mempolicy(2) , get_mempolicy(2) , mbind(2) , sched_setaffinity(2) ,
222       sched_getaffinity(2) , proc(5) , ftok(3) , shmat(2) , migratepages(8)
223
224
225
226
227SuSE Labs                          Mar 2004                         NUMACTL(8)
Impressum