1HWLOC-PS(1) hwloc HWLOC-PS(1)
2
6 hwloc-ps - List currently-running processes or threads that are bound
7
9 hwloc-ps [options]
10
12 -a List all processes, even those that are not bound to any spe‐
13 cific part of the machine.
14 --pid <pid>
16 Only show process of PID <pid>, even if it is not bound to
17 any specific part of the machine.
18 --name <name>
20 Only show processes whose name contains <name>, even if they
21 are not bound to any specific part of the machine. This is
22 not supported on all operating systems.
23 --uid <uid>
25 Only show processes of the user whose UID is <uid>, or pro‐
26 cesses of all users if all is given. By default, only pro‐
27 cesses of the current user are displayed. This is currently
28 only supported on Linux.
29 -p --physical
31 Report OS/physical indexes instead of logical indexes
32 -l --logical
34 Report logical indexes instead of physical/OS indexes (de‐
35 fault)
36 -c --cpuset
38 Show process bindings as cpusets instead of objects.
39 -t --threads
41 Show threads inside processes. If -a is given as well, list
42 all threads within each process. Otherwise, show all threads
43 inside each process where at least one thread is bound. This
44 is currently only supported on Linux.
45 --single-ancestor
47 When the object is bound to different objects, report their
48 common ancestor (even if it may be larger than the actual
49 binding).
50 -e --get-last-cpu-location
52 Report the last processors where the process/thread ran.
53 Note that the result may already be outdated when reported
54 since the operating system may move the tasks to other pro‐
55 cessors at any time according to the binding.
56 --disallowed
58 Include objects disallowed by administrative limitations.
59 --pid-cmd <cmd>
61 Append the output of the given command to each PID line. For
62 each displayed process ID, execute the command <cmd> <pid>
63 and append the first line of its output to the regular hwloc-
64 ps line.
65 --pid-cmd env=<name>
67 On Linux, try to read the value of environment variable name
68 in each process and display it at the end of the line.
69 --pid-cmd mpirank
71 On Linux, try to find the process MPI rank (by querying some
72 widespread environment variables) and display it at the end
73 of the line.
74 --json-server
77 Run the tool as a JSON server that waits for other process'
78 requests on a port and sends back binding information. See
79 contrib/hwloc-ps.www/ for details.
80 --json-port <port>
82 Use the given port number instead of the default 8888.
83 -v --verbose
85 Increase verbosity of the JSON server.
86 --short-name
88 Show only the process short name instead of the path.
89 --version Report version and exit.
91 -h --help Display help message and exit.
93
95 By default, hwloc-ps lists only those currently-running processes that
96 are bound. If -t is given, processes that are not bound but contain at
97 least one bound thread are also displayed, as well as all their
98 threads.
99 hwloc-ps displays process identifier, command-line and binding. The
101 binding may be reported as objects or cpusets.
102 By default, process bindings are restricted to the currently available
104 topology. If some processes are bound to processors that are not avail‐
105 able to the current process, they are ignored unless --disallowed is
106 given.
107 The output is a plain list. If you wish to annotate the hierarchical
109 topology with processes so as to see how they are actual distributed on
110 the machine, you might want to use lstopo --ps instead (which also only
111 shows processes that are bound).
112 The -a switch can be used to show all processes, if desired.
114
116 If a process is bound, it appears in the default output:
117 $ hwloc-ps
119 4759 Core:0 myprogram
120 If a process is bound on two cores of a larger package, the output will
122 show these cores. Option --single-ancestor will rather return the
123 package even if it is actually larger than the binding here (the
124 process is not bound to Core:0 of Package:0):
125 $ hwloc-ps
127 4863 Core:1 Core:2 myprogram
128 $ hwloc-ps --single-ancestor
129 4863 Package:0 myprogram
130 If a process is not bound but 3 of his 4 threads are bound, it only ap‐
132 pears in the thread-aware output (or if explicitly selected):
133 $ hwloc-ps
135 $ hwloc-ps -t
137 4759 Machine:0 myprogram
138 4759 Machine:0
139 4761 PU:0
140 4762 PU:2
141 4765 PU:1
142 $ hwloc-ps --pid 4759
144 4759 Machine:0 myprogram
145 On Linux, hwloc-ps may also display some process specific environment
147 variable at the end of the line. This is for instance useful for iden‐
148 tify MPI ranks among processes:
149 $ hwloc-ps --pid-cmd env=OMPI_COMM_WORLD_RANK
151 29093 PU:0 myprogram OMPI_COMM_WORLD_RANK=0
152 29094 PU:2 myprogram OMPI_COMM_WORLD_RANK=1
153 29095 PU:1 myprogram OMPI_COMM_WORLD_RANK=2
154 29096 PU:3 myprogram OMPI_COMM_WORLD_RANK=3
155 Some widespread MPI specific environment variables
157 (OMPI_COMM_WORLD_RANK, PMIX_RANK, PMI_RANK and SLURM_PROCID) are actu‐
158 ally directly recognized by hwloc-ps when requesting the mpirank com‐
159 mand:
160 $ hwloc-ps --pid-cmd mpirank
162 29093 PU:0 myprogram PMIX_RANK=0
163 29094 PU:2 myprogram PMIX_RANK=1
164 29095 PU:1 myprogram PMIX_RANK=2
165 29096 PU:3 myprogram PMIX_RANK=3
166 Beside reading environment variables, hwloc-ps may also append the out‐
168 put of a custom program. Again, for reading the Open MPI process rank:
169 $ hwloc-ps --pid-cmd myscript
171 29093 PU:0 myprogram OMPI_COMM_WORLD_RANK=0
172 29094 PU:2 myprogram OMPI_COMM_WORLD_RANK=1
173 29095 PU:1 myprogram OMPI_COMM_WORLD_RANK=2
174 29096 PU:3 myprogram OMPI_COMM_WORLD_RANK=3
175 where myscript is a shell script doing:
177 #!/bin/sh
179 cat /proc/$1/environ 2>/dev/null | xargs --null --max-args=1 echo |
180 grep OMPI_COMM_WORLD_RANK
181
184 hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1), and hwloc-
185 ps.www/README
1862.5.0 Jun 14, 2021 HWLOC-PS(1)