1HWLOC-GATHER-TOPOLOGY(1)             hwloc            HWLOC-GATHER-TOPOLOGY(1)
2
3
4

NAME

6       hwloc-gather-topology - Saves the relevant Linux topology files and the
7       lstopo output for later (possibly offline) usage.
8

SYNOPSIS

10       hwloc-gather-topology [options] <path>
11

OPTIONS

13       -h --help display help message and exit
14

DESCRIPTION

16       hwloc-gather-topology saves all the relevant topology files into an ar‐
17       chive  (<path>.tar.bz2)  and  the  lstopo  output (<path>.output).  The
18       utility for example  stores  the  /proc/cpuinfo  file  and  the  entire
19       /sys/devices/system/node/ directory tree.
20
21       These  files can be used later to explore the machine topology offline.
22       Once the tarball has been extracted, it may for instance  be  given  to
23       some  hwloc command-line utilities through their --input option.  It is
24       also possible to override the default topology that the  hwloc  library
25       will read by setting the extracted path in the HWLOC_FSROOT environment
26       variable.
27
28       Both archive and lstopo output may also be submitted to hwloc  develop‐
29       ers to debug issues remotely.
30
31       hwloc-gather-topology  is a Linux specific tool, it is not installed on
32       other operating systems.
33
34       NOTE: It is highly recommended that you read the hwloc(7) overview page
35       before reading this man page.
36

EXAMPLES

38       To store topology information to be used later (possibly on a different
39       host) please run:
40
41            hwloc-gather-topology /tmp/myhost
42
43       It will store all relevant topology files  in  the  /tmp/myhost.tar.bz2
44       archive  and  the  lstopo output in the /tmp/myhost.output file.  These
45       files can be transferred on another  host  for  later/offline  analysis
46       and/or as the input to various hwloc utilities.
47
48       To   use   these   data   with  hwloc  utilities  you  have  to  unpack
49       myhost.tar.bz2 archive first:
50
51            tar jxvf /tmp/myhost.tar.bz2
52
53       A new directory named myhost now contains all topology files.  Then you
54       ask  various hwloc utilities to use this topology instead of the one of
55       the real machine by passing --input myhost.  To  display  the  topology
56       just run:
57
58            lstopo --input ./myhost
59
60       It  is  not  necessary  that  the  topology is extracted in the current
61       directory, absolute or relative paths are also supported:
62
63            lstopo --input /path/to/remote/host/extracted/topology/
64
65       To see how hwloc would distribute 8 parallel jobs on the original host:
66
67            hwloc-distrib --input myhost --single 8
68
69       To get the corresponding physical indexes in the previous command:
70
71            hwloc-calc --input myhost  --po  --li  --proclist  $(hwloc-distrib
72       --input myhost --single 8)
73
74       Any  program  may  actually  override the default topology with a given
75       archived  one  even  if  it  does  not  have  a  --input  option.   The
76       HWLOC_FSROOT environment variable should be used to do so:
77
78            HWLOC_FSROOT=myhost  hwloc-calc  --po --li --proclist $(hwloc-dis‐
79       trib --single 8)
80
81       All these commands will produce the same output as if executed directly
82       on  the  host on which the topology information was originally gathered
83       by the hwloc-gather-topology script.
84

RETURN VALUE

86       Upon successful execution, hwloc-gather-topology  will  exit  with  the
87       code 0.
88
89       hwloc-gather-topology  will  return  nonzero exit status if any kind of
90       error occurs, such as (but not limited to) failure to  create  the  ar‐
91       chive or output file.
92

SEE ALSO

94       hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
95
96
97
98
991.5                              Jul 30, 2012         HWLOC-GATHER-TOPOLOGY(1)
Impressum