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 --children-of-pid <pid>
20 Only show process of PID <pid> and its hierarchy of children,
21 even if they are not bound to any specific part of the ma‐
22 chine.
23 --name <name>
25 Only show processes whose name contains <name>, even if they
26 are not bound to any specific part of the machine. This is
27 not supported on all operating systems.
28 --uid <uid>
30 Only show processes of the user whose UID is <uid>, or pro‐
31 cesses of all users if all is given. By default, only pro‐
32 cesses of the current user are displayed. This is currently
33 only supported on Linux.
34 -p --physical
36 Report OS/physical indexes instead of logical indexes
37 -l --logical
39 Report logical indexes instead of physical/OS indexes (de‐
40 fault)
41 -c --cpuset
43 Show process bindings as cpusets instead of objects.
44 -t --threads
46 Show threads inside processes. If -a is given as well, list
47 all threads within each process. Otherwise, show all threads
48 inside each process where at least one thread is bound. This
49 is currently only supported on Linux.
50 --single-ancestor
52 When the object is bound to different objects, report their
53 common ancestor (even if it may be larger than the actual
54 binding).
55 -e --get-last-cpu-location
57 Report the last processors where the process/thread ran.
58 Note that the result may already be outdated when reported
59 since the operating system may move the tasks to other pro‐
60 cessors at any time according to the binding.
61 --disallowed
63 Include objects disallowed by administrative limitations.
64 --pid-cmd <cmd>
66 Append the output of the given command to each PID line. For
67 each displayed process ID, execute the command <cmd> <pid>
68 and append the first line of its output to the regular hwloc-
69 ps line.
70 --pid-cmd env=<name>
72 On Linux, try to read the value of environment variable name
73 in each process and display it at the end of the line.
74 --pid-cmd mpirank
76 On Linux, try to find the process MPI rank (by querying some
77 widespread environment variables) and display it at the end
78 of the line.
79 --lstopo-misc <file>
82 Output a file that may be given to lstopo --misc-from for
83 displaying processes/threads as Misc objects. See EXAMPLES
84 below.
85 --json-server
87 Run the tool as a JSON server that waits for other process'
88 requests on a port and sends back binding information. See
89 contrib/hwloc-ps.www/ for details.
90 --json-port <port>
92 Use the given port number instead of the default 8888.
93 -v --verbose
95 Increase verbosity of the JSON server.
96 --short-name
98 Show only the process short name instead of the path.
99 --version Report version and exit.
101 -h --help Display help message and exit.
103
105 By default, hwloc-ps lists only those currently-running processes that
106 are bound. If -t is given, processes that are not bound but contain at
107 least one bound thread are also displayed, as well as all their
108 threads.
109 hwloc-ps displays process identifier, command-line and binding. The
111 binding may be reported as objects or cpusets.
112 By default, process bindings are restricted to the currently available
114 topology. If some processes are bound to processors that are not avail‐
115 able to the current process, they are ignored unless --disallowed is
116 given.
117 The output is a plain list. If you wish to annotate the hierarchical
119 topology with processes so as to see how they are actual distributed on
120 the machine, you might want to use lstopo --ps instead (which also only
121 shows processes that are bound).
122 The -a switch can be used to show all processes, if desired.
124
126 If a process is bound, it appears in the default output:
127 $ hwloc-ps
129 4759 Core:0 myprogram
130 If a process is bound on two cores of a larger package, the output will
132 show these cores. Option --single-ancestor will rather return the
133 package even if it is actually larger than the binding here (the
134 process is not bound to Core:0 of Package:0):
135 $ hwloc-ps
137 4863 Core:1 Core:2 myprogram
138 $ hwloc-ps --single-ancestor
139 4863 Package:0 myprogram
140 If a process is not bound but 3 of his 4 threads are bound, it only ap‐
142 pears in the thread-aware output (or if explicitly selected):
143 $ hwloc-ps
145 $ hwloc-ps -t
147 4759 Machine:0 myprogram
148 4759 Machine:0
149 4761 PU:0
150 4762 PU:2
151 4765 PU:1
152 $ hwloc-ps --pid 4759
154 4759 Machine:0 myprogram
155 The output may be a file that lstopo uses for adding Misc objects (more
157 flexible version of lstopo --top):
158 $ hwloc-ps --misc-from foo
160 $ cat foo
161 name=12444 myprogram
162 cpuset=0x000000f0
163 subtype=Process
164 name=12444 mythread1
166 cpuset=0x00000050
167 subtype=Thread
168 name=12444 mythread2
170 cpuset=0x000000a0
171 subtype=Thread
172 This may be directly given to lstopo:
174 $ hwloc-ps --misc-from - | lstopo --misc-from -
176 On Linux, hwloc-ps may also display some process specific environment
178 variable at the end of the line. This is for instance useful for iden‐
179 tify MPI ranks among processes:
180 $ hwloc-ps --pid-cmd env=OMPI_COMM_WORLD_RANK
182 29093 PU:0 myprogram OMPI_COMM_WORLD_RANK=0
183 29094 PU:2 myprogram OMPI_COMM_WORLD_RANK=1
184 29095 PU:1 myprogram OMPI_COMM_WORLD_RANK=2
185 29096 PU:3 myprogram OMPI_COMM_WORLD_RANK=3
186 Some widespread MPI specific environment variables
188 (OMPI_COMM_WORLD_RANK, PMIX_RANK, PMI_RANK and SLURM_PROCID) are actu‐
189 ally directly recognized by hwloc-ps when requesting the mpirank com‐
190 mand:
191 $ hwloc-ps --pid-cmd mpirank
193 29093 PU:0 myprogram PMIX_RANK=0
194 29094 PU:2 myprogram PMIX_RANK=1
195 29095 PU:1 myprogram PMIX_RANK=2
196 29096 PU:3 myprogram PMIX_RANK=3
197 Beside reading environment variables, hwloc-ps may also append the out‐
199 put of a custom program. Again, for reading the Open MPI process rank:
200 $ hwloc-ps --pid-cmd myscript
202 29093 PU:0 myprogram OMPI_COMM_WORLD_RANK=0
203 29094 PU:2 myprogram OMPI_COMM_WORLD_RANK=1
204 29095 PU:1 myprogram OMPI_COMM_WORLD_RANK=2
205 29096 PU:3 myprogram OMPI_COMM_WORLD_RANK=3
206 where myscript is a shell script doing:
208 #!/bin/sh
210 cat /proc/$1/environ 2>/dev/null | xargs --null --max-args=1 echo |
211 grep OMPI_COMM_WORLD_RANK
212
215 hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1), and hwloc-
216 ps.www/README
2172.10.0 Dec 04, 2023 HWLOC-PS(1)