Note that hwloc(7) provides a detailed explanation of the hwloc system and of valid <location> formats; it should be read before reading this man page.
If multiple locations are given, they are combined in the sense that the binding will be wider. The process will be allowed to run on every location inside the combination.
The list of input locations may be explicitly ended with "--".
If binding fails, or if the binding set is empty, and --force was not given, hwloc-bind returns with an error instead of launching the executable.
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.
To run the echo command on the first logical processor of the second package:
$ hwloc-bind package:1.pu:0 -- echo hello
which is exactly equivalent to the following line as long as there is no ambiguity between hwloc-bind option names and the executed command name:
$ hwloc-bind package:1.pu:0 echo hello
To bind the "echo" command to the first core of the second package and the second core of the first package:
$ hwloc-bind package:1.core:0 package:0.core:1 -- echo hello
To bind memory on the first high-bandwidth memory node:
$ hwloc-bind --membind hbm:0 -- echo hello $ hwloc-bind --membind --hbm numa:0 -- 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 packages on the second and third nodes:
$ hwloc-bind node:1-2.package:0:3 -- echo hello
which is also equivalent to:
$ hwloc-bind node:1-2.package: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 package with physical index 1:
$ hwloc-bind --physical package:1.core:2 -- echo hello
To run on odd cores within even packages:
$ hwloc-bind package:even.core:odd -- echo hello
To run on the first package, except on its second and fifth cores:
$ hwloc-bind package:0 ~package:0.core:1 ~package:0.core:4 -- echo hello
To run anywhere except on the first package:
$ hwloc-bind all ~package: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 supported by the OS):
$ hwloc-bind --cpubind node:1 --membind node:0 -- echo hello
The --get option can report current bindings. This example shows nesting hwloc-bind invocations to set a binding and then report it:
$ hwloc-bind node:1.package:2 -- hwloc-bind --get 0x00004444,0x44000000
hwloc-calc may convert this output into actual objects, either with logical or physical indexes:
$ hwloc-calc --physical -I pu `hwloc-bind --get` 26,30,34,38,42,46 $ hwloc-calc --logical -I pu `hwloc-bind --get` --sep " " 24 25 26 27 28 29
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.package:2` -- echo hello
The current memory binding may also be reported:
$ hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind --get --membind 0x000000f0 (interleave)
Note that if the system is not NUMA, the reported string may indicate that the process is bound to the entire system memory (e.g., "0xf...f").
$ 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.
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.