Provided by: hwloc-nox_1.11.9-1_amd64 bug


       hwloc-distrib - Build a number of cpu masks distributed on the system


       hwloc-distrib [options] <integer>


              Singlify each output to a single CPU.

              Show  CPU  set strings in the format recognized by the taskset command-line program
              instead of hwloc-specific CPU set string format.

       -v --verbose
              Verbose messages.

       -i <file>, --input <file>
              Read topology from XML file <file> (instead of  discovering  the  topology  on  the
              local  machine).   If  <file> is "-", the standard input is used.  XML support must
              have been compiled in to hwloc for this option to be usable.

       -i <directory>, --input <directory>
              Read topology from the chroot specified by <directory> (instead of discovering  the
              topology  on the local machine).  This option is generally only available on Linux.
              The chroot was usually created by gathering another machine  topology  with  hwloc-

       -i <specification>, --input <specification>
              Simulate  a  fake  hierarchy  (instead  of  discovering  the  topology on the local
              machine). If <specification> is "node:2 pu:3", the topology will contain  two  NUMA
              nodes with 3 processing units in each of them.  The <specification> string must end
              with a number of PUs.

       --if <format>, --input-format <format>
              Enforce the input in the given format, among xml, fsroot and synthetic.

       --ignore <type>
              Ignore all objects of type <type> in the topology.

       --from <type>
              Distribute starting from objects of the given type instead of from the top  of  the
              topology hierarchy, i.e. ignoring the structure given by objects above.

       --to <type>
              Distribute  down  to objects of the given type instead of down to the bottom of the
              topology hierarchy, i.e. ignoring the structure given by objects below.   This  may
              be  useful  if  some  latitude  is  desired for the binding, e.g. just bind several
              processes to each package without specifying a single core for each of them.

       --at <type>
              Distribute among objects of the given type.  This is equivalent to specifying  both
              --from and --to at the same time.

              Distribute  by  starting  with  the  last  objects  first, and singlify CPU sets by
              keeping the last bit (instead of the first bit).

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

              Do not consider administration limitations.

              Report version and exit.


       hwloc-distrib generates a series of CPU masks corresponding to a distribution of  a  given
       number  of elements over the topology of the machine. The distribution is done recursively
       from the top of the hierarchy (or from the level specified by option --from) down  to  the
       bottom  of the hierarchy (or down to the level specified by option --to, or until only one
       element remains), splitting the number of elements at each encountered hierarchy level not
       ignored by options --ignore.

       This  can  e.g.  be  used to distribute a set of processes hierarchically according to the
       topology of a machine. These masks can be used with hwloc-bind(1).

       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.


       hwloc-distrib's operation is best described through several examples.

       If 4 processes have to be distributed across a machine, their CPU masks  may  be  obtained

           $ hwloc-distrib 4

       To distribute only among the second package, the topology should be restricted:

           $ hwloc-distrib --restrict $(hwloc-calc package:1) 4

       To get a single processor of each CPU masks (prevent migration in case of binding)

           $ hwloc-distrib 4 --single

       Each output line may be converted independently with hwloc-calc:

           $ hwloc-distrib 4 --single | hwloc-calc --taskset

       To  convert  the output into a list of processors that may be passed to dplace -c inside a
       mpirun command line:

           $ hwloc-distrib 4 --single | xargs hwloc-calc --pulist


       Upon successful execution, hwloc-distrib displays one  or  more  CPU  mask  strings.   The
       return value is 0.

       hwloc-distrib  will  return  nonzero if any kind of error occurs, such as (but not limited
       to) failure to parse the command line.


       hwloc(7), hwloc-gather-topology(1)