<commit_before>.\" -*- nroff -*-
.\" Copyright © 2009-2013 Inria.  All rights reserved.
.\" Copyright © 2009-2010 Université of Bordeaux
.\" Copyright © 2009-2010 Cisco Systems, Inc.  All rights reserved.
.\" See COPYING in top-level directory.
.TH LSTOPO "1" "#HWLOC_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
.SH NAME
lstopo, lstopo-no-graphics \- Show the topology of the system
.
.\" **************************
.\"    Synopsis Section
.\" **************************
.SH SYNOPSIS
.
.B lstopo
[ \fIoptions \fR]... [ \fIfilename \fR]
.
.PP
.B lstopo-no-graphics
[ \fIoptions \fR]... [ \fIfilename \fR]
.
.PP
Note that hwloc(7) provides a detailed explanation of the hwloc system; it
should be read before reading this man page
.
.\" **************************
.\"    Options Section
.\" **************************
.SH OPTIONS
.
.TP
\fB\-\-of\fR <format>, \fB\-\-output\-format\fR <format>
Enforce the output in the given format.
See the OUTPUT FORMATS section below.
.TP
\fB\-i\fR <file>, \fB\-\-input\fR <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.
.TP
\fB\-i\fR <directory>, \fB\-\-input\fR <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-gather-topology.
.TP
\fB\-i\fR <specification>, \fB\-\-input\fR <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.
.TP
\fB\-\-if\fR <format>, \fB\-\-input\-format\fR <format>
Enforce the input in the given format, among \fBxml\fR, \fBfsroot\fR
and \fBsynthetic\fR.
.TP
\fB\-v\fR \fB\-\-verbose\fR
Include additional detail.
.TP
\fB\-s\fR \fB\-\-silent\fR
Reduce the amount of details to show.
.TP
\fB\-l\fR \fB\-\-logical\fR
Display hwloc logical indexes instead of physical/OS indexes (default for console output).
These indexes are prefixed with "L#".
The physical indexes of some objects (PU and Node by default, all
objects if verbose) will appear as object attribute "P#...".
.TP
\fB\-p\fR \fB\-\-physical\fR
Display OS/physical indexes instead of hwloc logical indexes (default for graphical output).
These indexes are prefixed with "P#" instead of "L#" in the console output.
.TP
\fB\-c\fR \fB\-\-cpuset\fR
Display the cpuset of each object.
.TP
\fB\-C\fR \fB\-\-cpuset\-only\fR
Only display the cpuset of each object; do not display anything else
about the object.
.TP
\fB\-\-taskset\fR
Show CPU set strings in the format recognized by the taskset command-line
program instead of hwloc-specific CPU set string format.
This option should be combined with \fB\-\-cpuset\fR or \fB\-\-cpuset\-only\fR,
otherwise it will imply \fB\-\-cpuset\fR.
.TP
\fB\-\-only\fR <type>
Only show objects of the given type in the textual output.
.TP
\fB\-\-ignore\fR <type>
Ignore all objects of type <type> in the topology.
hwloc supports ignoring any type except PUs and I/O devices.
However lstopo still offers PU ignoring by hiding PU objects
in the graphical and textual outputs.
Note that PU may not be ignored in the XML output.
.TP
\fB\-\-no\-caches\fR
Do not show caches.
.TP
\fB\-\-no\-useless\-caches\fR
Do not show caches which do not have a hierarchical impact.
.TP
\fB\-\-no\-icaches\fR
Do not show Instruction caches, only Data and Unified caches are displayed.
.TP
\fB\-\-whole\-system\fR
Do not consider administration limitations.
.TP
\fB\-\-merge\fR
Do not show levels that do not have a hierarchical impact.
.TP
\fB\-\-restrict\fR <cpuset>
Restrict the topology to the given cpuset.
.TP
\fB\-\-restrict\fR binding
Restrict the topology to the current process binding.
This option requires the use of the actual current machine topology
(or any other topology with \fB\-\-thissystem\fR or with
HWLOC_THISSYSTEM set to 1 in the environment).
.TP
\fB\-\-no\-io\fB
Do not show any I/O device or bridge.
By default, common devices (GPUs, NICs, block devices, ...) and
interesting bridges are shown.
.TP
\fB\-\-no\-bridges\fB
Do not show any I/O bridge except hostbridges.
By default, common devices (GPUs, NICs, block devices, ...) and
interesting bridges are shown.
.TP
\fB\-\-whole\-io\fB
Show all I/O devices and bridges.
By default, only common devices (GPUs, NICs, block devices, ...) and
interesting bridges are shown.
.TP
\fB\-\-thissystem\fR
Assume that the selected backend provides the topology for the
system on which we are running. 
This is useful when using \fB\-\-restrict\fR binding and loading
a custom topology such as an XML file.
.TP
\fB\-\-pid\fR <pid>
Detect topology as seen by process <pid>, i.e. as if process <pid> did the
discovery itself.
Note that this can for instance change the set of allowed processors.
Also show this process current CPU binding by marking the corresponding
PUs (in Green in the graphical output, see the COLORS section below,
or by appending \fI(binding)\fR to the verbose text output).
If 0 is given as pid, the current binding for the lstopo process will be shown.
.TP
\fB\-\-ps\fR \fB\-\-top\fR
Show existing processes as misc objects in the output. To avoid uselessly
cluttering the output, only processes that are restricted to some part of the
machine are shown.  On Linux, kernel threads are not shown.
If many processes appear, the output may become hard to read anyway,
making the hwloc-ps program more practical.
.TP
\fB\-\-fontsize\fR <size>
Set size of text font.
.TP
\fB\-\-gridsize\fR <size>
Set size of margin between elements.
.TP
\fB\-\-horiz\fR, \fB\-\-horiz\fR=<type1,...>
Horizontal graphical layout instead of nearly 4/3 ratio.
If a comma-separated list of types is given, the layout only
applies to the corresponding containers.
.TP
\fB\-\-vert\fR, \fB\-\-vert\fR=<type1,...>
Vertical graphical layout instead of nearly 4/3 ratio.
If a comma-separated list of types is given, the layout only
applies to the corresponding containers.
.TP
\fB\-\-no\-legend\fR
Remove the text legend at the bottom.
.TP
\fB\-\-version\fR
Report version and exit.
.
.\" **************************
.\"    Description Section
.\" **************************
.SH DESCRIPTION
.
lstopo and lstopo-no-graphics are capable of displaying a topological map of
the system in a variety of different output formats.  The only difference
between lstopo and lstopo-no-graphics is that graphical outputs are only
supported by lstopo, to reduce dependencies on external libraries.
.
.PP
If no filename is specified and the DISPLAY environment variable is set,
lstopo displays the map in a graphical window.  If no filename is
specified and the DISPLAY environment variable is
.I not
set, a text summary is displayed.
.
.PP
The filename specified directly implies the output format that will be
used; see the OUTPUT FORMATS section, below.  Output formats that
support color will indicate specific characteristics about individual
CPUs by their color; see the COLORS section, below.
.
.\" **************************
.\"    Output Formats Section
.\" **************************
.SH OUTPUT FORMATS
.
.PP
The filename on the command line usually determines the format of the output.
There are a few filenames that indicate specific output formats and
devices (e.g., a filename of "-" will output a text summary to
stdout), but most filenames indicate the desired output format by 
their suffix (e.g., "topo.png" will output a PNG-format file).
.PP
The format of the output may also be changed with "\-\-of".
For instance, "\-\-of pdf" will generate a PDF-format file on the standard
output, while "\-\-of fig toto" will output a Xfig-format file named "toto".

.PP
The list of currently supported formats is given below. Any of them may
be used with "\-\-of" or as a filename suffix.
.TP
.B default
Send the output to a window or to the console depending on the environment.
.
.TP
.B console
Send a text summary to stdout.
Binding, unallowed or offline processors are only annotated in this mode
if verbose; see the COLORS section, below.
.
.TP
.B txt
Output an ASCII art representation of the map.
If outputting to stdout and if colors are supported on the terminal,
the output will be colorized.
.
.TP
.B fig
Output a representation of the map that can be loaded in Xfig.
.
.TP
.B pdf
If lstopo was compiled with the proper
support, lstopo outputs a PDF representation of the map.
.
.TP
.B ps
If lstopo was compiled with the proper
support, lstopo outputs a Postscript representation of the map.
.
.TP
.B png
If lstopo was compiled with the proper
support, lstopo outputs a PNG representation of the map.
.
.TP
.B svg
If lstopo was compiled with the proper
support, lstopo outputs an SVG representation of the map.
.
.TP
.B synthetic
If the topology is symmetric
(which requires that the root object has its symmetric_subtree field set),
lstopo outputs a synthetic description string.
This output may be reused as an input synthetic topology
description later.
Note that I/O devices often cause topology asymmetry.
Adding \-\-no\-io may then be useful when the synthetic export fails.
See also the Synthetic topologies section in the documentation.
.
.TP
.B xml
If lstopo was compiled with the proper
support, lstopo outputs an XML representation of the map.
It may be reused later, even on another machine, with lstopo \-\-input,
the HWLOC_XMLFILE environment variable, or the hwloc_topology_set_xml()
function.

.PP
The following special names may be used:
.TP
.B \-
Send a text summary to stdout.
.
.TP
.B /dev/stdout
Send a text summary to stdout.  It is effectively the same as
specifying "\-".
.
.TP
.B \-.<format>
If the entire filename is "\-.<format>", lstopo behaves as if
"\-\-of <format> -" was given, which means a file of the given format
is sent to the standard output.

.PP
See the output of "lstopo \-\-help" for a specific list of what
graphical output formats are supported in your hwloc installation.
.
.\" **************************
.\"    Colors Section
.\" **************************
.SH COLORS
Individual CPUs are colored in the semi-graphical and graphical output
formats to indicate different characteristics:
.TP
Green
The topology is reported as seen by a specific process (see \fB\-\-pid\fR),
and the given CPU is in this process CPU binding mask.
.TP
White
The CPU is in the allowed set (see below).
If the topology is reported as seen by a specific process (see \fB\-\-pid\fR),
the given CPU is also not in this process CPU binding mask.
.TP
Red
The CPU is not in the allowed set (see below).
.TP
Black
The CPU is offline (not all OS's support displaying offline CPUs).
.
.PP
The "allowed set" is the set of CPUs to which the current process is
allowed to bind.  The allowed set is usually either inherited from the
parent process or set by administrative qpolicies on the system.  Linux
cpusets are one example of limiting the allowed set for a process and
its children to be less than the full set of CPUs on the system.
.PP
Different processes may therefore have different CPUs in the allowed
set.  Hence, invoking lstopo in different contexts and/or as different
users may display different colors for the same individual CPUs (e.g.,
running lstopo in one context may show a specific CPU as red, but
running lstopo in a different context may show the same CPU as white).
.PP
Some lstopo output modes, e.g. the console mode (default non-graphical output),
do not support colors at all.
The console mode displays the above characteristics by appending text
to each PU line if verbose messages are enabled.
.
.\" **************************
.\"    Layout Section
.\" **************************
.SH LAYOUT
In its graphical output, lstopo uses simple rectangular heuristics
to try to achieve a 4/3 ratio between width and height. However,
in the particular case of NUMA nodes, the layout is always a flat
rectangle, to avoid letting the user believe any particular NUMA
topology (lstopo is not able to render that yet).
.
.\" **************************
.\"    Examples Section
.\" **************************
.SH EXAMPLES
.
To display the machine topology in textual mode:

    lstopo-no-graphics

To display the machine topology in pseudo-graphical mode:

    lstopo-no-graphics -.txt

To display in graphical mode (assuming that the DISPLAY environment
variable is set to a relevant value):

    lstopo

To export the topology to a PNG file:

    lstopo file.png

To export an XML file on a machine and later display the corresponding
graphical output on another machine:

    machine1$ lstopo file.xml
    <transfer file.xml from machine1 to machine2>
    machine2$ lstopo --input file.xml

To save the current machine topology to XML and later reload it faster
while still considering it as the current machine:

   $ lstopo file.xml
   <...>
   $ lstopo --input file.xml --thissystem

To restrict an XML topology to only physical processors 0, 1, 4 and 5:

    lstopo --input file.xml --restrict 0x33 newfile.xml

To restrict an XML topology to only numa node whose logical index is 1:

    lstopo --input file.xml --restrict $(hwloc-calc --input file.xml node:1) newfile.xml

To display a summary of the topology:

    lstopo -s

To get more details about the topology:

    lstopo -v

To only show cores:

    lstopo --only core

To show cpusets:

    lstopo --cpuset

To only show the cpusets of sockets:

    lstopo --only socket --cpuset-only

Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
processor units:

    lstopo --input "n:2 2"

To count the number of logical processors in the system

   lstopo --only pu | wc -l
.\" **************************
.\"    See also section
.\" **************************
.SH SEE ALSO
.
.ft R
hwloc-info(1), hwloc-bind(1), hwloc-ps(1), hwloc-gather-topology(1)
.sp<commit_msg>lstopo(1) SEE ALSO should also point to hwloc(7...<commit_after>.\" -*- nroff -*-
.\" Copyright © 2009-2013 Inria.  All rights reserved.
.\" Copyright © 2009-2010 Université of Bordeaux
.\" Copyright © 2009-2010 Cisco Systems, Inc.  All rights reserved.
.\" See COPYING in top-level directory.
.TH LSTOPO "1" "#HWLOC_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
.SH NAME
lstopo, lstopo-no-graphics \- Show the topology of the system
.
.\" **************************
.\"    Synopsis Section
.\" **************************
.SH SYNOPSIS
.
.B lstopo
[ \fIoptions \fR]... [ \fIfilename \fR]
.
.PP
.B lstopo-no-graphics
[ \fIoptions \fR]... [ \fIfilename \fR]
.
.PP
Note that hwloc(7) provides a detailed explanation of the hwloc system; it
should be read before reading this man page
.
.\" **************************
.\"    Options Section
.\" **************************
.SH OPTIONS
.
.TP
\fB\-\-of\fR <format>, \fB\-\-output\-format\fR <format>
Enforce the output in the given format.
See the OUTPUT FORMATS section below.
.TP
\fB\-i\fR <file>, \fB\-\-input\fR <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.
.TP
\fB\-i\fR <directory>, \fB\-\-input\fR <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-gather-topology.
.TP
\fB\-i\fR <specification>, \fB\-\-input\fR <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.
.TP
\fB\-\-if\fR <format>, \fB\-\-input\-format\fR <format>
Enforce the input in the given format, among \fBxml\fR, \fBfsroot\fR
and \fBsynthetic\fR.
.TP
\fB\-v\fR \fB\-\-verbose\fR
Include additional detail.
.TP
\fB\-s\fR \fB\-\-silent\fR
Reduce the amount of details to show.
.TP
\fB\-l\fR \fB\-\-logical\fR
Display hwloc logical indexes instead of physical/OS indexes (default for console output).
These indexes are prefixed with "L#".
The physical indexes of some objects (PU and Node by default, all
objects if verbose) will appear as object attribute "P#...".
.TP
\fB\-p\fR \fB\-\-physical\fR
Display OS/physical indexes instead of hwloc logical indexes (default for graphical output).
These indexes are prefixed with "P#" instead of "L#" in the console output.
.TP
\fB\-c\fR \fB\-\-cpuset\fR
Display the cpuset of each object.
.TP
\fB\-C\fR \fB\-\-cpuset\-only\fR
Only display the cpuset of each object; do not display anything else
about the object.
.TP
\fB\-\-taskset\fR
Show CPU set strings in the format recognized by the taskset command-line
program instead of hwloc-specific CPU set string format.
This option should be combined with \fB\-\-cpuset\fR or \fB\-\-cpuset\-only\fR,
otherwise it will imply \fB\-\-cpuset\fR.
.TP
\fB\-\-only\fR <type>
Only show objects of the given type in the textual output.
.TP
\fB\-\-ignore\fR <type>
Ignore all objects of type <type> in the topology.
hwloc supports ignoring any type except PUs and I/O devices.
However lstopo still offers PU ignoring by hiding PU objects
in the graphical and textual outputs.
Note that PU may not be ignored in the XML output.
.TP
\fB\-\-no\-caches\fR
Do not show caches.
.TP
\fB\-\-no\-useless\-caches\fR
Do not show caches which do not have a hierarchical impact.
.TP
\fB\-\-no\-icaches\fR
Do not show Instruction caches, only Data and Unified caches are displayed.
.TP
\fB\-\-whole\-system\fR
Do not consider administration limitations.
.TP
\fB\-\-merge\fR
Do not show levels that do not have a hierarchical impact.
.TP
\fB\-\-restrict\fR <cpuset>
Restrict the topology to the given cpuset.
.TP
\fB\-\-restrict\fR binding
Restrict the topology to the current process binding.
This option requires the use of the actual current machine topology
(or any other topology with \fB\-\-thissystem\fR or with
HWLOC_THISSYSTEM set to 1 in the environment).
.TP
\fB\-\-no\-io\fB
Do not show any I/O device or bridge.
By default, common devices (GPUs, NICs, block devices, ...) and
interesting bridges are shown.
.TP
\fB\-\-no\-bridges\fB
Do not show any I/O bridge except hostbridges.
By default, common devices (GPUs, NICs, block devices, ...) and
interesting bridges are shown.
.TP
\fB\-\-whole\-io\fB
Show all I/O devices and bridges.
By default, only common devices (GPUs, NICs, block devices, ...) and
interesting bridges are shown.
.TP
\fB\-\-thissystem\fR
Assume that the selected backend provides the topology for the
system on which we are running. 
This is useful when using \fB\-\-restrict\fR binding and loading
a custom topology such as an XML file.
.TP
\fB\-\-pid\fR <pid>
Detect topology as seen by process <pid>, i.e. as if process <pid> did the
discovery itself.
Note that this can for instance change the set of allowed processors.
Also show this process current CPU binding by marking the corresponding
PUs (in Green in the graphical output, see the COLORS section below,
or by appending \fI(binding)\fR to the verbose text output).
If 0 is given as pid, the current binding for the lstopo process will be shown.
.TP
\fB\-\-ps\fR \fB\-\-top\fR
Show existing processes as misc objects in the output. To avoid uselessly
cluttering the output, only processes that are restricted to some part of the
machine are shown.  On Linux, kernel threads are not shown.
If many processes appear, the output may become hard to read anyway,
making the hwloc-ps program more practical.
.TP
\fB\-\-fontsize\fR <size>
Set size of text font.
.TP
\fB\-\-gridsize\fR <size>
Set size of margin between elements.
.TP
\fB\-\-horiz\fR, \fB\-\-horiz\fR=<type1,...>
Horizontal graphical layout instead of nearly 4/3 ratio.
If a comma-separated list of types is given, the layout only
applies to the corresponding containers.
.TP
\fB\-\-vert\fR, \fB\-\-vert\fR=<type1,...>
Vertical graphical layout instead of nearly 4/3 ratio.
If a comma-separated list of types is given, the layout only
applies to the corresponding containers.
.TP
\fB\-\-no\-legend\fR
Remove the text legend at the bottom.
.TP
\fB\-\-version\fR
Report version and exit.
.
.\" **************************
.\"    Description Section
.\" **************************
.SH DESCRIPTION
.
lstopo and lstopo-no-graphics are capable of displaying a topological map of
the system in a variety of different output formats.  The only difference
between lstopo and lstopo-no-graphics is that graphical outputs are only
supported by lstopo, to reduce dependencies on external libraries.
.
.PP
If no filename is specified and the DISPLAY environment variable is set,
lstopo displays the map in a graphical window.  If no filename is
specified and the DISPLAY environment variable is
.I not
set, a text summary is displayed.
.
.PP
The filename specified directly implies the output format that will be
used; see the OUTPUT FORMATS section, below.  Output formats that
support color will indicate specific characteristics about individual
CPUs by their color; see the COLORS section, below.
.
.\" **************************
.\"    Output Formats Section
.\" **************************
.SH OUTPUT FORMATS
.
.PP
The filename on the command line usually determines the format of the output.
There are a few filenames that indicate specific output formats and
devices (e.g., a filename of "-" will output a text summary to
stdout), but most filenames indicate the desired output format by 
their suffix (e.g., "topo.png" will output a PNG-format file).
.PP
The format of the output may also be changed with "\-\-of".
For instance, "\-\-of pdf" will generate a PDF-format file on the standard
output, while "\-\-of fig toto" will output a Xfig-format file named "toto".

.PP
The list of currently supported formats is given below. Any of them may
be used with "\-\-of" or as a filename suffix.
.TP
.B default
Send the output to a window or to the console depending on the environment.
.
.TP
.B console
Send a text summary to stdout.
Binding, unallowed or offline processors are only annotated in this mode
if verbose; see the COLORS section, below.
.
.TP
.B txt
Output an ASCII art representation of the map.
If outputting to stdout and if colors are supported on the terminal,
the output will be colorized.
.
.TP
.B fig
Output a representation of the map that can be loaded in Xfig.
.
.TP
.B pdf
If lstopo was compiled with the proper
support, lstopo outputs a PDF representation of the map.
.
.TP
.B ps
If lstopo was compiled with the proper
support, lstopo outputs a Postscript representation of the map.
.
.TP
.B png
If lstopo was compiled with the proper
support, lstopo outputs a PNG representation of the map.
.
.TP
.B svg
If lstopo was compiled with the proper
support, lstopo outputs an SVG representation of the map.
.
.TP
.B synthetic
If the topology is symmetric
(which requires that the root object has its symmetric_subtree field set),
lstopo outputs a synthetic description string.
This output may be reused as an input synthetic topology
description later.
Note that I/O devices often cause topology asymmetry.
Adding \-\-no\-io may then be useful when the synthetic export fails.
See also the Synthetic topologies section in the documentation.
.
.TP
.B xml
If lstopo was compiled with the proper
support, lstopo outputs an XML representation of the map.
It may be reused later, even on another machine, with lstopo \-\-input,
the HWLOC_XMLFILE environment variable, or the hwloc_topology_set_xml()
function.

.PP
The following special names may be used:
.TP
.B \-
Send a text summary to stdout.
.
.TP
.B /dev/stdout
Send a text summary to stdout.  It is effectively the same as
specifying "\-".
.
.TP
.B \-.<format>
If the entire filename is "\-.<format>", lstopo behaves as if
"\-\-of <format> -" was given, which means a file of the given format
is sent to the standard output.

.PP
See the output of "lstopo \-\-help" for a specific list of what
graphical output formats are supported in your hwloc installation.
.
.\" **************************
.\"    Colors Section
.\" **************************
.SH COLORS
Individual CPUs are colored in the semi-graphical and graphical output
formats to indicate different characteristics:
.TP
Green
The topology is reported as seen by a specific process (see \fB\-\-pid\fR),
and the given CPU is in this process CPU binding mask.
.TP
White
The CPU is in the allowed set (see below).
If the topology is reported as seen by a specific process (see \fB\-\-pid\fR),
the given CPU is also not in this process CPU binding mask.
.TP
Red
The CPU is not in the allowed set (see below).
.TP
Black
The CPU is offline (not all OS's support displaying offline CPUs).
.
.PP
The "allowed set" is the set of CPUs to which the current process is
allowed to bind.  The allowed set is usually either inherited from the
parent process or set by administrative qpolicies on the system.  Linux
cpusets are one example of limiting the allowed set for a process and
its children to be less than the full set of CPUs on the system.
.PP
Different processes may therefore have different CPUs in the allowed
set.  Hence, invoking lstopo in different contexts and/or as different
users may display different colors for the same individual CPUs (e.g.,
running lstopo in one context may show a specific CPU as red, but
running lstopo in a different context may show the same CPU as white).
.PP
Some lstopo output modes, e.g. the console mode (default non-graphical output),
do not support colors at all.
The console mode displays the above characteristics by appending text
to each PU line if verbose messages are enabled.
.
.\" **************************
.\"    Layout Section
.\" **************************
.SH LAYOUT
In its graphical output, lstopo uses simple rectangular heuristics
to try to achieve a 4/3 ratio between width and height. However,
in the particular case of NUMA nodes, the layout is always a flat
rectangle, to avoid letting the user believe any particular NUMA
topology (lstopo is not able to render that yet).
.
.\" **************************
.\"    Examples Section
.\" **************************
.SH EXAMPLES
.
To display the machine topology in textual mode:

    lstopo-no-graphics

To display the machine topology in pseudo-graphical mode:

    lstopo-no-graphics -.txt

To display in graphical mode (assuming that the DISPLAY environment
variable is set to a relevant value):

    lstopo

To export the topology to a PNG file:

    lstopo file.png

To export an XML file on a machine and later display the corresponding
graphical output on another machine:

    machine1$ lstopo file.xml
    <transfer file.xml from machine1 to machine2>
    machine2$ lstopo --input file.xml

To save the current machine topology to XML and later reload it faster
while still considering it as the current machine:

   $ lstopo file.xml
   <...>
   $ lstopo --input file.xml --thissystem

To restrict an XML topology to only physical processors 0, 1, 4 and 5:

    lstopo --input file.xml --restrict 0x33 newfile.xml

To restrict an XML topology to only numa node whose logical index is 1:

    lstopo --input file.xml --restrict $(hwloc-calc --input file.xml node:1) newfile.xml

To display a summary of the topology:

    lstopo -s

To get more details about the topology:

    lstopo -v

To only show cores:

    lstopo --only core

To show cpusets:

    lstopo --cpuset

To only show the cpusets of sockets:

    lstopo --only socket --cpuset-only

Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
processor units:

    lstopo --input "n:2 2"

To count the number of logical processors in the system

   lstopo --only pu | wc -l
.\" **************************
.\"    See also section
.\" **************************
.SH SEE ALSO
.
.ft R
hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-ps(1), hwloc-gather-topology(1)
.sp
{'fraction_non_alphanumeric': 0.11239581486079092, 'fraction_numerical': 0.004362475616244015, 'mean_word_length': 3.527296082209377, 'pattern_counts': {'":': 0, '<': 65, '<?xml version=': 0, '>': 65, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 26}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4578734', 'n_tokens_mistral': 8810, 'n_tokens_neox': 8232, 'n_words': 4107}