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

OPTIONS

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

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

       --whole-system
                 Do not consider administration limitations.

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

DESCRIPTION

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

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

       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 ALSO

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