HWLOC-BIND(1) hwloc HWLOC-BIND(1)NAMEhwloc-bind - Launch a command that is bound to specific processors
and/or memory.
SYNOPSIShwloc-bind [options] <location1> [<location2> [...] ] [--] <command>
...
OPTIONS
See below for a description of valid <location> formats.
--cpubind Use following arguments for CPU binding (default).
--membind Use following arguments for memory binding. If --mempolicy
is not also given, the default policy is bind.
--mempolicy <policy>
Change the memory binding policy. The available policies are
default, firsttouch, bind, interleave replicate and next‐
touch. This option is only meaningful when an actual binding
is also given with --membind. If --membind is given without
--mempolicy, the default policy is bind.
--get Report the current bindings. When combined with --membind,
report the memory binding instead of CPU binding.
--get-last-cpu-location
Report the last processors where the process ran. Note that
the result may already be outdated when reported since the
operating system may move the process to other processors at
any time according to the binding. This option cannot be
combined with --membind.
--single Bind on a single CPU to prevent migration.
--strict Require strict binding.
--pid <pid>
Operate on pid <pid>
-p --physical
take OS/physical indexes instead of logical indexes
-l --logical
take logical indexes instead of physical/OS indexes (default)
--taskset Display CPU set strings in the format recognized by the
taskset command-line program instead of hwloc-specific CPU
set string format. This option has no impact on the format
of input CPU set strings, both formats are always accepted.
-v Verbose output.
--version Report version and exit.
DESCRIPTIONhwloc-bind execs an executable (with optional command line arguments)
that is bound to the specified location (or list of locations). Upon
successful execution, hwloc-bind simply sets bindings and then execs
the executable over itself.
NOTE: It is highly recommended that you read the hwloc(7) overview page
before reading this man page. Most of the concepts described in
hwloc(7) directly apply to the hwloc-bind utility.
EXAMPLES
hwloc-bind's operation is best described through several examples.
More details about how locations are specified on the hwloc-bind com‐
mand line are described in hwloc(7).
To run the echo command on the first logical processor of the second
socket:
hwloc-bind socket:1.pu:0 -- echo hello
which is exactly equivalent to
hwloc-bind socket:1.pu:0 echo hello
To bind the "echo" command to the first core of the second socket and
the second core of the first socket:
hwloc-bind socket:1.core:0 socket:0.core:1 echo hello
Note that binding the "echo" command to multiple processors is probably
meaningless (because "echo" is likely implemented as a single-threaded
application); these examples just serve to show what hwloc-bind can do.
To run on the first three sockets on the second and third nodes:
hwloc-bind node:1-2.socket:0:3 echo hello
which is also equivalent to:
hwloc-bind node:1-2.socket:0-2 echo hello
Note that if you attempt to bind to objects that do not exist, hwloc-
bind will not warn unless -v was specified.
To run on processor with physical index 2 in socket with physical index
1:
hwloc-bind--physical socket:1.core:2 echo hello
To run on odd cores within even sockets:
hwloc-bind socket:even.core:odd echo hello
To run on the first socket, except on its second and fifth cores:
hwloc-bind socket:0 ~socket:0.core:1 ~socket:0.core:4 echo hello
To run anywhere except on the first socket:
hwloc-bind all ~socket:0 echo hello
To run on a core near the network interface named eth0:
hwloc-bind os=eth0 echo hello
To run on a core near the PCI device whose bus ID is 0000:01:02.0:
hwloc-bind pci=0000:01:02.0 echo hello
To bind memory on second memory node and run on first node (when sup‐
ported by the OS):
hwloc-bind--cpubind node:1 --membind node:0 echo hello
The --get option can report current bindings. This example shows nest‐
ing hwloc-bind invocations to set a binding and then report it:
hwloc-bind node:1.socket:2 hwloc-bind--get
On one of the hwloc developer's machines, this example reports
"0x00004444,0x44000000". The mask reported on your machine may be dif‐
ferent.
Locations may also be specified as a hex bit mask (typically generated
by hwloc-calc). For example:
hwloc-bind 0x00004444,0x44000000 echo hello
hwloc-bind `hwloc-calc node:1.socket:2` echo hello
Memory binding may also be reported:
hwloc-bind--membind node:1 --mempolicy interleave --hwloc-bind--get --membind
This returns a string describing the memory binding, such as
"0x000000f0 (interleave)". Note that if the system does not contain
any NUMA nodes, the reported string will indicate that the process is
bound to the entire system memory (e.g., "0xf...f").
HINT
If the graphics-enabled lstopo is available, use for instance
hwloc-bind core:2 -- lstopo --pid 0
to check what the result of your binding command actually is. lstopo
will graphically show where it is bound to by hwloc-bind.
RETURN VALUE
Upon successful execution, hwloc-bind execs the command over itself.
The return value is therefore whatever the return value of the command
is.
hwloc-bind will return nonzero if any kind of error occurs, such as
(but not limited to): failure to parse the command line, failure to
retrieve process bindings, or lack of a command to execute.
SEE ALSOhwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)1.5 Jul 30, 2012 HWLOC-BIND(1)
