1HWLOC-BIND(1) hwloc HWLOC-BIND(1)
2
6 hwloc-bind - Launch a command that is bound to specific processors
7 and/or memory.
8
10 hwloc-bind [options] <location1> [<location2> [...] ] [--] <command>
11 ...
12
14 See below for a description of valid <location> formats.
15 --cpubind Use following arguments for CPU binding (default).
17 --membind Use following arguments for memory binding. If --mempolicy
19 is not also given, the default policy is bind.
20 --mempolicy <policy>
22 Change the memory binding policy. The available policies are
23 default, firsttouch, bind, interleave replicate and next‐
24 touch. This option is only meaningful when an actual binding
25 is also given with --membind. If --membind is given without
26 --mempolicy, the default policy is bind.
27 --get Report the current bindings. When combined with --membind,
29 report the memory binding instead of CPU binding.
30 --get-last-cpu-location
32 Report the last processors where the process ran. Note that
33 the result may already be outdated when reported since the
34 operating system may move the process to other processors at
35 any time according to the binding. This option cannot be
36 combined with --membind.
37 --single Bind on a single CPU to prevent migration.
39 --strict Require strict binding.
41 --pid <pid>
43 Operate on pid <pid>
44 -p --physical
46 take OS/physical indexes instead of logical indexes
47 -l --logical
49 take logical indexes instead of physical/OS indexes (default)
50 --taskset Display CPU set strings in the format recognized by the
52 taskset command-line program instead of hwloc-specific CPU
53 set string format. This option has no impact on the format
54 of input CPU set strings, both formats are always accepted.
55 -v Verbose output.
57 --version Report version and exit.
59
61 hwloc-bind execs an executable (with optional command line arguments)
62 that is bound to the specified location (or list of locations). Upon
63 successful execution, hwloc-bind simply sets bindings and then execs
64 the executable over itself.
65 NOTE: It is highly recommended that you read the hwloc(7) overview page
67 before reading this man page. Most of the concepts described in
68 hwloc(7) directly apply to the hwloc-bind utility.
69
71 hwloc-bind's operation is best described through several examples.
72 More details about how locations are specified on the hwloc-bind com‐
73 mand line are described in hwloc(7).
74 To run the echo command on the first logical processor of the second
76 socket:
77 hwloc-bind socket:1.pu:0 -- echo hello
79 which is exactly equivalent to
81 hwloc-bind socket:1.pu:0 echo hello
83 To bind the "echo" command to the first core of the second socket and
85 the second core of the first socket:
86 hwloc-bind socket:1.core:0 socket:0.core:1 echo hello
88 Note that binding the "echo" command to multiple processors is probably
90 meaningless (because "echo" is likely implemented as a single-threaded
91 application); these examples just serve to show what hwloc-bind can do.
92 To run on the first three sockets on the second and third nodes:
94 hwloc-bind node:1-2.socket:0:3 echo hello
96 which is also equivalent to:
98 hwloc-bind node:1-2.socket:0-2 echo hello
100 Note that if you attempt to bind to objects that do not exist, hwloc-
102 bind will not warn unless -v was specified.
103 To run on processor with physical index 2 in socket with physical index
105 1:
106 hwloc-bind --physical socket:1.core:2 echo hello
108 To run on odd cores within even sockets:
110 hwloc-bind socket:even.core:odd echo hello
112 To run on the first socket, except on its second and fifth cores:
114 hwloc-bind socket:0 ~socket:0.core:1 ~socket:0.core:4 echo hello
116 To run anywhere except on the first socket:
118 hwloc-bind all ~socket:0 echo hello
120 To run on a core near the network interface named eth0:
122 hwloc-bind os=eth0 echo hello
124 To run on a core near the PCI device whose bus ID is 0000:01:02.0:
126 hwloc-bind pci=0000:01:02.0 echo hello
128 To bind memory on second memory node and run on first node (when sup‐
130 ported by the OS):
131 hwloc-bind --cpubind node:1 --membind node:0 echo hello
133 The --get option can report current bindings. This example shows nest‐
135 ing hwloc-bind invocations to set a binding and then report it:
136 hwloc-bind node:1.socket:2 hwloc-bind --get
138 On one of the hwloc developer's machines, this example reports
140 "0x00004444,0x44000000". The mask reported on your machine may be dif‐
141 ferent.
142 Locations may also be specified as a hex bit mask (typically generated
144 by hwloc-calc). For example:
145 hwloc-bind 0x00004444,0x44000000 echo hello
147 hwloc-bind `hwloc-calc node:1.socket:2` echo hello
148 Memory binding may also be reported:
150 hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind
152 --get --membind
153 This returns a string describing the memory binding, such as
155 "0x000000f0 (interleave)". Note that if the system does not contain
156 any NUMA nodes, the reported string will indicate that the process is
157 bound to the entire system memory (e.g., "0xf...f").
158
160 If the graphics-enabled lstopo is available, use for instance
161 hwloc-bind core:2 -- lstopo --pid 0
163 to check what the result of your binding command actually is. lstopo
165 will graphically show where it is bound to by hwloc-bind.
166
168 Upon successful execution, hwloc-bind execs the command over itself.
169 The return value is therefore whatever the return value of the command
170 is.
171 hwloc-bind will return nonzero if any kind of error occurs, such as
173 (but not limited to): failure to parse the command line, failure to
174 retrieve process bindings, or lack of a command to execute.
175
177 hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
1781.5 Jul 30, 2012 HWLOC-BIND(1)