Provided by: hwloc_2.9.2-1_amd64 bug

NAME

       hwloc-bind  -  Launch  a  command  that  is bound to specific processors and/or memory, or
       consult the binding of an existing program

SYNOPSIS

       hwloc-bind [topology options] [options] <location1> [<location2> [...]  ]  [--]  <command>
       ...

       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.

TOPOLOGY OPTIONS

       All topology options must be given before all other options.

       --no-smt, --no-smt=<N>
                 Only keep the first PU per core before binding.  If <N> is specified,  keep  the
                 <N>-th  instead,  if  any.   PUs  are  ordered  by  physical  index  during this
                 filtering.

                 Note that this option is applied  after  searching  locations.   Hence  --no-smt
                 pu:2-5  will  first select the PUs #2 to #5 in the machine before binding on one
                 of them per core.  To rather bind on PUs #2 to #5 after filtering one per  core,
                 you should combine with hwloc-calc:

                   hwloc-bind  $(hwloc-calc --restrict $(hwloc-calc --no-smt all) pu:2-5) -- echo
                 hello

       --restrict <cpuset>
                 Restrict the topology to the given cpuset.

       --restrict nodeset=<nodeset>
                 Restrict the topology to the given nodeset,  unless  --restrict-flags  specifies
                 something different.

       --restrict-flags <flags>
                 Enforce  flags  when  restricting  the  topology.  Flags may be given as numeric
                 values  or  as  a  comma-separated  list  of  flag  names  that  are  passed  to
                 hwloc_topology_restrict().   Those  names may be substrings of actual flag names
                 as long as a single one matches, for instance bynodeset,memless.  The default is
                 0 (or none).

       --disallowed
                 Include objects disallowed by administrative limitations.

       --best-memattr <name>
                 Select  the  best NUMA node among the given memory binding set by looking at the
                 memory attribute given by <name> (or as an index).

                 If the memory attribute values depend on the initiator, the CPU binding  set  is
                 used as the initiator.

                 Standard  attribute  names  are Capacity, Locality, Bandwidth, and Latency.  All
                 existing attributes in the current topology may be listed with

                     $ lstopo --memattrs

       --hbm     Only take high bandwidth memory nodes (Intel Xeon Phi MCDRAM)  in  account  when
                 looking for NUMA nodes in the input locations.

                 This  option must be combined with NUMA node locations, such as --hbm numa:1 for
                 binding on the second HBM node.  It may also be written as hbm:1.

       --no-hbm  Ignore high bandwidth memory nodes (Intel Xeon Phi MCDRAM) when looking for NUMA
                 nodes in the input locations.

OPTIONS

       All these options must be given after all topology options above.

       --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 and nexttouch.  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.   The  output  is  an opaque bitmask that may be
                 translated into objects with hwloc-calc (see EXAMPLES below).

                 When a command is given, the binding is displayed before executing the  command.
                 When  no  command  is  given,  the  program  exits  after displaying the current
                 binding.

                 When combined with --membind, report the memory binding instead of CPU binding.

                 No location may be given since no binding is performed.

       --nodeset Report binding as a NUMA memory node set instead of  a  CPU  set  if  --get  was
                 given.   This  is useful for manipulating CPU-less NUMA nodes since their cpuset
                 is empty while their nodeset is correct.

                 Also parse input bitmasks as nodesets instead of cpusets.

                 When this option is not passed, individual input bitmasks may still be parsed as
                 nodesets if they are prefixed with nodeset=.

       -e --get-last-cpu-location
                 Report  the  last  processors  where  the  process ran.  The output is an opaque
                 bitmask that may be  translated  into  objects  with  hwloc-calc  (see  EXAMPLES
                 below).

                 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.

                 When  a  command is given, the last processors is displayed before executing the
                 command. When no command is given, the program exits after displaying  the  last
                 processors.

                 This option cannot be combined with --membind.

                 No location may be given since no binding is performed.

       --single  Bind on a single CPU to prevent migration.

       --strict  Require strict binding.

       --pid <pid>
                 Operate on pid <pid>

       --tid <tid>
                 Operate  on  thread  <tid> instead of on an entire process.  The feature is only
                 supported on Linux for thread CPU binding, or for reporting the  last  processor
                 where the thread ran if -e was also passed.

       -p --physical
                 Interpret  input  locations with OS/physical indexes instead of logical indexes.
                 This option does not apply to the output, see --get above.

       -l --logical
                 Interpret input locations with logical indexes instead  of  physical/OS  indexes
                 (default).  This option does not apply to the output, see --get above.

       --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.

       -f --force
                 Launch the executable even if binding failed.

       -q --quiet
                 Hide  non-fatal  error messages.  It includes locations pointing to non-existing
                 objects, as well as failure to bind.  This is  usually  useful  in  addition  to
                 --force.

       -v --verbose
                 Verbose output.

       --version Report version and exit.

       -h --help Display help message and exit.

DESCRIPTION

       hwloc-bind execs an executable (with optional command line arguments) that is bound to the
       specified location (or  list  of  locations).   Location  specification  is  described  in
       hwloc(7).   Upon  successful execution, hwloc-bind simply sets bindings and then execs the
       executable over itself.

       If a bitmask location is given with prefix nodeset=,  then  it  is  considered  a  nodeset
       instead of a CPU set. See also --nodeset.

       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.

EXAMPLES

       hwloc-bind's operation is best described through several examples.  More details about how
       locations are specified on the hwloc-bind command line are described in hwloc(7).

       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 on the first PU of all cores of the first package:

           $ hwloc-bind package:0.core:all.pu:0 -- echo hello
           $ hwloc-bind --no-smt package:0 -- echo hello

       To bind on the memory node local to a PU with largest capacity:

           $ hwloc-bind --best-memattr capacity --cpubind pu:23 --membind pu:23 -- echo hello

       To bind memory on the first high-bandwidth memory node on Intel Xeon Phi:

           $ hwloc-bind --membind hbm:0 -- echo hello
           $ hwloc-bind --hbm --membind 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

       hwloc-bind  does  not  have  an option to select a kind of CPU core but it may be combined
       with hwloc-calc to do so. For instance, to bind on the first two cores whose kind  matches
       CoreType=IntelAtom:

           $  hwloc-bind  $(hwloc-calc  --restrict $(hwloc-calc --cpukind CoreType=IntelAtom all)
       core:0-1) -- 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  can also be used to convert cpu mask strings to human-readable package/core/PU
       strings; see the description of -H in  hwloc-calc(1)  for  more  details.   The  following
       example  binds  to all the PUs in a specific core, uses the --get option to retrieve where
       the process was actually bound, and then uses hwloc-calc to display the resulting cpu mask
       in space-delimited list of human-readable locations:

           $ hwloc-bind package:1.core:2 -- hwloc-bind --get | hwloc-calc -H package.core.pu
           Package:1.Core:2.PU:0 Package:1.Core:2.PU:1

       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)

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 ALSO

       hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)