.\" -*- nroff -*-
.\" Copyright © Jirka Hladky
.TH hwloc-gather-topology.sh "1" "#HWLOC_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
.SH NAME
hwloc-gather-topology.sh \- Saves the Linux topology files (/sys, /proc, ...) into SAVEPATH.tar.bz2 archive and expected lstopo's output into SAVEPATH.output file for later (possibly offline) usage.
.
.\" **************************
.\"    Synopsis Section
.\" **************************
.SH SYNOPSIS
.
.B hwloc-gather-topology.sh
[\fIoptions\fR] \fI<SAVEPATH> \fR
.
.\" **************************
.\"    Options Section
.\" **************************
.SH OPTIONS
.
\fB\-h\fR \fB\-\-help\fR
display help message and exit
.
.\" **************************
.\"    Description Section
.\" **************************
.SH DESCRIPTION
.
hwloc-gather-topology.sh can be used to save all the kernel's CPU 
and NUMA topology relevant files into SAVEPATH.tar.bz2 archive. 
The utility stores for example /proc/cpuinfo, /proc/meminfo and 
/sys/devices/system/cpu/ and /sys/devices/system/node/ directory trees.
These files can be used later to run various hwloc tools offline to explore
CPU and NUMA topology. It can be submitted to hwloc's developers as well 
to debug any issues.
.
.PP
.B NOTE:
It is highly recommended that you read the hwloc(7) overview page
before reading this man page.
.
.\" **************************
.\"    Examples Section
.\" **************************
.SH EXAMPLES
.PP
To store CPU and NUMA topology data to be used later (possibly on different host) 
please run:
.PP
hwloc-gather-topology.sh /tmp/host_topology
.PP
It will store all topology relevant files in
.B
/tmp/host_topology.tar.bz2
archive and expected lstopo's output in
.B
/tmp/host_topology.output
file.
.
These files can be transferred on another host for later analysis and/or as the input to
various hwloc's utilities.
.PP
To use these data with hwloc's utilities you have to unpack
.B
host_topology.tar.bz2
archive first:
.PP
tar jxvf /tmp/host.tar.bz2
.PP
It will create directory named
.B
host_topology
with all topology relevant files.
Then you can execute various hwloc's utilities by using 
.B
--input host_topology 
command line option.
To display the topology just run:
.PP
lstopo --input host_topology
.PP
To see how hwloc would distribute 8 parallel jobs on the host just run:
.PP
hwloc-distrib --input host_topology --single 8
.PP
To get more user friendly output (logical CPU indexes as displayed for example by top(1)) of the previous command try following:
.PP
hwloc-calc --input host_topology --po --li --proclist $(hwloc-distrib --input host_topology --single 8)
.PP
All these commands will produce the same output as if executed directly on the host on which the topology information was originally stored by using hwloc-gather-topology.sh script.
.\" **************************
.\"    Return value section
.\" **************************
.SH RETURN VALUE
Upon successful execution, hwloc-gather-topology.sh will exit with the code 0. 
.
.PP
hwloc-bind will return nonzero exit status if any kind of error occurs, such as
(but not limited to) failure to write into directory $(dirname SAVEPATH).
.\" **************************
.\"    See also section
.\" **************************
.SH SEE ALSO
.
.ft R
hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
.sp